Can I have my GitHub Pages index.html in a subfolder of the repository?

Solution 1:

Create a dummy index.html at the root and put this in your header:

<meta http-equiv="refresh" content="0; url=https://repo.github.io/folder/index.html">

Be sure to change the destination URL. This will instantly redirect from index.html to your folder/index.html.

Solution 2:

Maybe you want to push a subtree. For instance, let's say you have the build/dist directory and there the Doxygen site is built.

After building, to make sure to commit all changes in that folder, then do the following.

git subtree push --prefix build/dist origin gh-pages

It's important that you don't have anything on the gh-pages branch, on local or origin.

All credit goes to: https://gist.github.com/cobyism/4730490

Initially I also thought of a redirect. But redirects feel like code smells, even HTTP redirects. Although sometimes unavoidable, here may be a cleaner solution, and it is probably what you were looking for.

Solution 3:

You now have the option to use the /docs folder of the master branch as the root of your GitHub Pages website.

Solution 4:

To use Doxygen and gh-pages, you need to:

  1. Create the file .nojekyll in the root of your gh-pages branch
  2. Make sure you removed .png, .html, and similars from your .gitignore file
  3. And finally, create the index.html file in the root of your project:

    <!DOCTYPE HTML>
    <html lang="en-US">
        <head>
            <meta charset="UTF-8">
            <meta http-equiv="refresh" content="1;url=html/index.html">
            <title>Page Redirection</title>
        </head>
        <body>
            If you are not redirected automatically, 
            follow the <a href="html/index.html">link to the documentation</a>
        </body>
    </html>
    

References:

  1. GitHub Pages (github.io) doxygen generated page not found (404)
  2. How to automatically generate doxygen documentation using Travis
  3. Auto-deploying Doxygen documentation to gh-pages with Travis CI
  4. https://help.github.com/categories/github-pages-basics/
  5. Publish Your Project Documentation with GitHub Pages
  6. How to make an introduction page with Doxygen