How to Publish a Static Site with GitHub Pages

On this page

1. Create a public repository for the practice site #

Create a new repository named field-notes-site. Choose public visibility for the GitHub Free route. This is a project site, so its default address will include /field-notes-site/. A user site at the root of your account uses the special <your-username>.github.io repository name instead (site types).

Use invented material for the example. A public repository exposes its files and history. Passwords, private documents and real customer details don't belong in the practice site. Deleting a secret from the latest file doesn't make its earlier history disappear.

For local editing later, free Git GUI clients offer a visual way to manage commits. You can complete this first deployment using only GitHub's browser editor.

2. Add the homepage as index.html #

In the repository, use Add file → Create new file. Name the file exactly index.html and enter this original sample:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Field Notes</title>
</head>
<body>
  <main>
    <h1>Field Notes</h1>
    <p>A small public collection of weekend observations.</p>
    <p><a href="about.html">About these notes</a></p>
  </main>
</body>
</html>

Commit the file to your main branch. Use a message such as Add practice homepage. You should see index.html in the repository's top-level file list. The viewport line helps the page render at a phone's width, and the language attribute identifies the text language.

The exact lowercase filename matters. Index.html and index.HTML aren't equivalent on the publishing server. GitHub's entry-file instructions also allow Markdown entry files, but HTML keeps this example independent of a theme.

3. Add a second page and check its relative link #

Create about.html in the same directory:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>About Field Notes</title>
</head>
<body>
  <main>
    <h1>About Field Notes</h1>
    <p>This practice site contains invented sample material.</p>
    <p><a href="index.html">Return to Field Notes</a></p>
  </main>
</body>
</html>

Commit it. The relative about.html link stays under the project directory. A link starting with /about.html would point to the account domain's root instead, which can be the wrong location for a project site.

For larger content, a Markdown editor and a static site generator can replace manual HTML writing. First get the two-page example working so you have a simple reference when troubleshooting a generated site.

4. Publish a static site with GitHub Pages from the source branch #

Open Settings → Pages in the repository. Under Build and deployment, set Source to Deploy from a branch. Select the branch holding your files, normally main, and choose /(root). Click Save (official settings workflow).

If your files are in a docs directory, choose that directory instead. For this example they're at the root. The folder setting must match the files' location; changing it doesn't move the files for you.

Branch publishing normally runs through GitHub's Jekyll build path. For prebuilt output containing folders that Jekyll would treat specially, GitHub documents a .nojekyll file in the publishing source. Our two ordinary HTML files don't need a generator-specific configuration.

5. Wait for the deployment and open the published address #

Look at the repository's Actions tab if deployment is still pending or fails. Open the Pages workflow run to see its build and deployment status. After a successful publication, return to Settings → Pages and select Visit site.

Don't guess the address from the repository's clone URL. Use the published link supplied by Pages. Open it in a separate tab and check that the main heading is Field Notes. Follow About these notes, then follow the return link. Both should load normal pages without a 404.

If the site isn't ready yet, inspect the deployment status before editing unrelated settings. A pending deployment and a failed deployment need different next steps. GitHub's troubleshooting reference lists entry-file and source-location checks.

6. Make one small update and verify the release #

Edit the homepage paragraph to A small public collection of weekend walks and observations. Commit the change to the selected publishing branch. Wait for the next Pages deployment to complete, then reload the public page.

You should see the revised sentence, and the second-page link should still work. This checks that a later edit reaches the published page. Record the source branch and folder in the README so the next editor doesn't have to rediscover them.

For a finished portfolio, code editors and image compression tools help with editing and media preparation. Keep the deployment settings stable while you add those assets.

Known problems with the first deployment #

A September 2025 GitHub discussion described an Actions deployment failing at the Pages-site lookup. Replies explained that Pages must be enabled with a matching publishing source. For this guide, keep Deploy from a branch selected; if you later adopt a custom Actions workflow, change the source to GitHub Actions.

In a May 2026 404 discussion, replies focused on filename case and output location. Check each filename against its URL, including asset folders. Some replies in public discussions mention PHP, but Pages doesn't execute server-side PHP; use the official Pages documentation for the hosting scope.

Troubleshooting table #

Variations for your next website #

Publish a user site at the account root

Use the repository name <your-username>.github.io if you want the default site at your account's root address. That differs from the project example, whose URL includes the repository name. Recheck links if you move between those two shapes.

Publish a generated documentation site

Use a generator's official GitHub Pages instructions and build output. GitHub recommends a custom Actions workflow for build processes beyond Jekyll. Keep the generator's base-path setting consistent with the project URL, then check a deeply nested page as well as the homepage.

Add a custom domain after the default site works

Follow GitHub's custom-domain documentation. Domain verification, DNS and HTTPS are separate from the HTML deployment. Start with the working github.io site so a DNS problem doesn't hide a publishing problem.

Completion checklist #

• The repository and sample content are intentionally public.
• index.html and about.html are at the selected source root.
• Pages points to the right branch and directory.
• Actions shows a successful deployment.
• The published homepage, second page and return link all work.
• A small update appeared after its next deployment.
• The README records how the site is published.

Next steps #

Explore Cloudflare Pages if you want branch previews, or Netlify for another Git-connected publishing workflow. GitHub Pages remains a straightforward home for this public two-page site. Add content gradually and check navigation after each structural change.