How do I get a free JS.ORG subdomain for my GitHub Pages site?
JS.ORG offers free subdomains such as https://foo.js.org to JavaScript developers who host a project on GitHub Pages, provided the page has reasonable content with a clear connection to JavaScript. The process has four steps: set up your GitHub Page, choose a subdomain based on your existing GitHub Pages URL, add a CNAME file to your repo, and open a pull request against the JS.ORG repository. Your new URL should go live within 24 hours.
Before you start
You need:
- A GitHub account.
- A GitHub Pages site that already has some reasonable content.
- A clear JavaScript connection on that page — this is the stated requirement for approval.
You keep complete control over your published content as the repository owner, but all rights and duties that come with publishing a website remain your responsibility.
Step 1: Set up your GitHub Page
If you haven't already, log in to GitHub and set up your GitHub Page following GitHub's instructions. Make sure you add some reasonable content to the new page before continuing — an empty or unrelated page is unlikely to pass review.
Step 2: Choose your js.org subdomain
Your subdomain must be derived from your existing GitHub Pages URL. For a page at http://foo.github.io/bar, either of these is possible:
foo.js.org(your username)bar.js.org(your repo name)
More details are available in the JS.ORG wiki.
Step 3: Add a CNAME file
Add a file named CNAME to your repo. For project pages, place it in the gh-pages branch. The file should contain a single line matching the domain you chose, for example:
foo.js.org
No quotes. If you run into problems, check the "Custom URLs" section of the GitHub Pages Help.
Step 4: Open a pull request
Make a pull request in the JS.ORG GitHub repository that adds your subdomain to the list of existing JS.ORG domains. Your new URL should go live within 24 hours.
Keep an eye on your pull request in case of a naming conflict or a question from the JS.ORG side.
Quick reference
| Step | Action | Where |
|---|---|---|
| 1 | Create and populate a GitHub Page | Your GitHub account |
| 2 | Pick username- or repo-based subdomain | From your GitHub Pages URL |
| 3 | Add CNAME with the chosen domain |
Your repo (gh-pages branch for project pages) |
| 4 | Submit a pull request adding your subdomain | JS.ORG GitHub repository |
Common snags
- Naming conflict — someone may already have claimed the subdomain you want; watch your pull request for feedback.
- Content review — the page must have a clear connection to JavaScript; unrelated content can hold up or block approval.
- Wrong CNAME location — for project pages the file belongs in the
gh-pagesbranch, not the default branch. - Timing — allow up to 24 hours after your pull request is merged for the URL to go live.