How to Create a Multi-Page Navigation Structure on GitHub Pages

How to Create a Multi-Page Navigation Structure on GitHub Pages?

After enabling GitHub Pages from repository settings, many users wonder: how can I build a site that isn’t just a single page? How do I create links between multiple HTML files, and how do I organize them?

The answer is: it’s simpler than you think. Whether you use plain HTML or a static site generator like Jekyll, GitHub Pages fully supports multi-page sites. You just need the right folder structure, internal links, and optional navigation UI.

Step 1: Understand Folder and URL Mapping

GitHub Pages serves content based on the folder and filename structure in your publishing branch.

For example:

• index.html → /
• about.html → /about.html
• contact/index.html → /contact/
• docs/getting-started.html → /docs/getting-started.html

Each file becomes a page. Links between them are just standard HTML <a href> elements.

Step 2: Build Navigation Using Static Links

You can create a header or sidebar that links between your pages. Example:

<nav>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about.html">About</a></li>
    <li><a href="/projects/index.html">Projects</a></li>
    <li><a href="/contact/index.html">Contact</a></li>
  </ul>
</nav>

This menu can be copied across pages manually or injected via a templating system like Jekyll.

Step 3: Organize Pages in Logical Folders

Organize your site like this:

/index.html
/about.html
/projects/index.html
/projects/2025-case-study.html
/contact/index.html

Now, each folder acts as a page section, and users can navigate cleanly using breadcrumb or sidebar links.

Step 4: Use Relative Paths When Needed

From inside /projects/, a link back to homepage can be:

<a href="../index.html">Home</a>

But for consistency and SEO, it’s better to use absolute paths like:

<a href="/index.html">Home</a>

These remain reliable regardless of nesting level.

Step 5: Create a Navigation Partial (Jekyll Optional)

If using Jekyll, you can avoid repeating navigation on every page by creating a reusable _includes/nav.html file and inserting it with:

{% raw %}{% include nav.html %}{% endraw %}

This way, updating the nav bar in one file updates all pages that include it.

Step 6: Add Active State to Current Page

Let visitors know where they are by highlighting the current page in the navigation. You can use JavaScript or conditional classes (in Jekyll):

<li class="{% raw %}{% if page.url == '/about.html' %}active{% endif %}{% endraw %}"><a href="/about.html">About</a></li>

Step 7: Use Clean URLs (Optional)

Instead of /about.html, you can create folders with index.html inside:

/about/index.html → /about/

This feels cleaner and more modern, especially when shared as links.

Step 8: Add a Sitemap or Table of Contents

For larger sites, it helps to include a sitemap:

<ul>
  <li><a href="/">Home</a></li>
  <li><a href="/docs/">Documentation</a>
    <ul>
      <li><a href="/docs/getting-started.html">Getting Started</a></li>
      <li><a href="/docs/configuration.html">Configuration</a></li>
    </ul>
  </li>
</ul>

This helps both users and search engines discover your pages.

Final Thoughts

GitHub Pages supports fully structured websites, not just single landing pages. By organizing your files smartly and creating internal links, you can build professional static websites that are easy to navigate and maintain.

Whether you're using pure HTML or Jekyll, a solid navigation system enhances user experience, reduces confusion, and keeps visitors engaged across multiple pages. It’s one of the most important features to get right once you’ve enabled GitHub Pages via the repository settings.