Quickstart Publish your first site with Claude Code

Step 5 · Publish

Turn on GitHub Pages

GitHub Pages turns the files on your main branch into a public website. You switch it on once. After that, every push to main updates your site.

Time: 10 min

Before you start, check two things:

  • Your repo is public. On a free GitHub account, Pages works only from public repos.
  • Its name is lowercase. The part of the address after .github.io/ must match your repo's name exactly, capitals included, so an all-lowercase name is easiest. Has capitals? Rename it yourself on GitHub: click Settings, type the new name in Repository name and click Rename. Do it before you switch Pages on, because a site address doesn't follow a rename.
How GitHub Pages turns your repo into a website At the top is your repo on GitHub, your-username/your-repo, with two settings: the branch, main, and the folder, either / (root) or /docs. An arrow labeled you switch it on once leads to GitHub Pages, which rebuilds the site after every push to main. An arrow labeled up to 10 minutes leads to your live site at https://your-username.github.io/your-repo/. Below, the address is taken apart piece by piece: your-username is your GitHub username, .github.io is GitHub's Pages address, and /your-repo/ is your repo name, spelled exactly as on GitHub, capitals included. Your repo on GitHub your-username/your-repo branch main folder / (root) or /docs you switch it on once GitHub Pages rebuilds after every push to main up to 10 minutes Your live site https://your-username .github.io/your-repo/ The address, piece by piece your-username your GitHub username .github.io GitHub's Pages address /your-repo/ your repo name, spelled exactly, capitals too
Pages publishes one branch and one folder of your repo. Your site's address is built from your username and your repo name.

Switch it on

Pick the folder that holds your site's index.html: / (root) for history-of-tampa, or /docs for startup-india-guide.

Wait for it

The first publish can take up to 10 minutes. To watch it, open your repo's Actions tab: a run called pages build and deployment appears, and a green check means it's done. Settings → Pages then shows "Your site is live at …" with a Visit site button.

If it goes wrong

I get a 404 page
  • Wait the full 10 minutes, then reload.
  • In Settings → Pages, check the branch is main and the folder is the one that holds index.html.
  • The start page must be named index.html, all lowercase.
  • Type the part after .github.io/ exactly as your repo's name is spelled, capitals included.

Or let the agent look:

Say this
My site at https://your-username.github.io/your-repo/ shows a 404. Check that index.html, in lowercase, is in the folder GitHub Pages publishes from on main, tell me which branch and folder Pages should use, and fix anything in the repo.
The page loads, but with no styling or broken images

The page can't find its files, usually because a path starts with /, points to the original owner's site, or doesn't match a file name's capital letters.

Say this
Some styles or images don't load on my live site. Find links to this repo's own CSS, JavaScript and image files that start with / or point to the original owner's site, and make them relative. Leave links to other services alone, such as map, chart and font libraries and hot-linked photos, and keep the share-image (og:image) address a full https:// link. Check that each file name matches its link exactly, including capital letters. Then commit and push to main.
It still shows the old version

Wait for the green check in the Actions tab. Then open the address in a private or incognito window, which skips the copy your browser saved. Still old? Your change may not be on main; see The main branch.

What the optional shortcut runs 
# Turn on Pages from main, root folder (use /docs for a site in docs/)
gh api -X POST repos/your-username/your-repo/pages -f "source[branch]=main" -f "source[path]=/"

# Show the Pages settings and the site's address
gh api repos/your-username/your-repo/pages

Saved only in this browser.