If I understand correctly, you're looking for a way to make the latest generated HTML documentation available from your repository without cluttering the main branch with generated files or forcing users to download them.

GitHub Pages is actually intended for this use case. You don't need to commit the generated documentation to your main branch. Instead, you can publish it to a dedicated gh-pages branch (or via the Pages deployment workflow), while keeping your source code separate.

This also addresses your concern about replacing documentation files on every release—the deployment simply publishes the newly generated documentation, so there's no need to manually manage those files in your main branch.

As for the HTML rendering, the reason your index.html was displayed as source code is that files viewed directly in a repository are served as file contents. When the same files are served through GitHub Pages, they are rendered as a website, so relative links between HTML files, CSS, JavaScript, and images work as expected.

Hope that helps!

Okay, yes you seem to understand my needs and concerns correctly.
However, although I understand what you mean by publishing it from a gh-pages branch, I am curious what you mean by "or via the Pages deployment workflow"?
Are you saying that I can skip the branch altogether and release it from some sort of workflow process?
I am very new to GitHub and have yet to create a release. Are saying that I can update the "published pages" as part of my release process?
I would very much like to understand what you mean by that.

The best practice is not to commit generated HTML documentation into your main source branch.

Instead, use GitHub Pages with an automated workflow:

• Generate the documentation during your release process (e.g., with Doxygen, Sphinx, Javadoc, etc.).

• Use a GitHub Actions workflow to publish the generated HTML to GitHub Pages.

• The documentation is hosted separately from your source code, so developers cloning the repository don't download generated files.

• You can add the Pages URL to:

  • the repository description,
  • the README,
  • or the repository's Website field so it appears in the repository sidebar.

This avoids all of the concerns you listed:

• ✅ No generated HTML committed to your source branch.
• ✅ No manual deletion/replacement of documentation files every release.
• ✅ Documentation updates automatically with each release or push.
• ✅ HTML is served as a website, so relative links work correctly. Opening index.html from the repository itself shows the source, because GitHub serves repository files as text rather than rendering them as web pages.

If you want documentation tied to each release, another common approach is:

• Publish the latest docs on GitHub Pages.
• Attach a ZIP of the generated documentation as a release asset for each tagged release, so users can download the docs that match a specific version.

Overall, the typical setup is:

Source code
      │
      ▼
GitHub Actions
      │
Generate HTML docs
      │
      ├── Deploy latest → GitHub Pages
      └── Attach docs.zip → GitHub Release

This is the approach used by many open-source projects because it keeps the repository clean while still providing browsable, versioned documentation.