Reputation: 1503

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

I'm trying to use GitHub pages to host a Doxygen site. Ideally, I'd like to be able to push the generated files and directories to GitHub without having to tweak them at all.

This, however, means that my index.html is in a subfolder of the repository and GitHub Pages isn't picking it up (I get a 404 when I try to access the Pages site). Is there a way to make GitHub recognise that index.html when it's in a subfolder?

It is a project site.

Upvotes: 58

Answers (10)

Darwin

Reputation: 2057

You can do that from settings tab.

Upvotes: 1

Rai

Reputation: 455

FTR, after trying everything else, the only way I could make it work was by creating a symlink called docs in root (e.g. in my case and using Windows's CMD by simply: mklink /d docs .\ScriptResources\ls\docs) targeting the real folder anywhere along the repo structure where I have my index.htm, assets or whatever it needs.

I don't know if this setup will run into some limitation from GitHub's part regarding other functions expecting a "real" docs folder in root, but in this case it solved the problem for me and there it is for what it may be worth.

Upvotes: 1

Ingo

Reputation: 746

The question is mainly about having the index.html in a subfolder of the repository. But it is focused on the Doxygen html documentation. So I will also respect this. I had the same problem and it took me some time to understand it a bit. So I will give it to the community and also for my own documentation for later reuse.

As shown by Agustín Amenabar in his answer you can just copy valid content to the origin Github Pages (origin gh-pages) and it can be shown for example as web site on address https://ingo-h.github.io/simple_tests/. But You have to ensure that you only copy the "rooted" subfolder (nothing to do for "rooting" except placing an index.html there). This can be done e.g. with

~$ git subtree push --prefix build/docs/html origin gh-pages

Thanks to cobyism for his nice idea. Doing this you will automatically get a branch remotes/origin/gh-pages in your repository. You can also just ~$ git switch gh-pages to it and have it local. I don't have a deeper look at it for what it can be good. On my test environment I get this:

~$ git branch --all
  dev
  gh-pages
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/dev
  remotes/origin/gh-pages
  remotes/origin/main

On your Github Actions tab you also find a workflow log pages-build-deployment. Looking at it you will find that the web site is build by default with Jekyll (blog-aware application). As we will see later, this is sub optimal with Doxygen.

Assuming you have a valid source, with this handmade deployment you have first to push its content and then deploy it:

~$ git push
~$ git subtree push --prefix build/docs/html origin gh-pages

To avoid the second step you can enable to use the docs/ directory or a Github Workflow as described at Configuring a publishing source for your GitHub Pages site. They will trigger the deployment with a push. These workflows create a Fragment to deploy that is equivalent to the subtree push. They do not create a remotes/origin/gh-pages branch on your repository.

Both options use Jekyll to build the web site from the sources because it is assumed that they are markdown sources that have to be translated to html. But for Doxygen it is wasted performance because its web pages are already build to a web site, ready for use. Fortunately Github provides a workflow template 'static.yml` that only uploads content without using Jekyll. This should be used for Doxygen html documentation because it should increase the upload speed a lot. When enabling the workflow use on configuring Github pages you should select StaticHTML:

When clicking Configure you can edit the workflow. At the end you find the source path:

  - name: Upload artifact
    uses: actions/upload-pages-artifact@v3
    with:
      # Upload entire repository
      path: '.'

Here you can set your source path, e.g.:

      # My source path
      path: 'build/docs/html'

By the way, you must be signed in as the owner of the repository, otherwise you will not find the "settings" button to get to the "Pages" configuration as described with the link above. I usually manage my repositories as contributor with all rights but that is not enough to setup "Pages". There is no hint about this and it took me some annoying time to find it out.

Upvotes: 0

Abhinas Regmi -mergeSort-

Reputation: 81

If your index.html is inside a folder in your repository and to deploy it you can use choose deployment option to github actions and then choose jekyll now the important part when you set your jekyll-gh-pages.yml for github action you don't have to modify the file content except for

source whose default is ./ change to the subfolder where your index.html is

for me my index.html was inside the frontend folder so I did as above

Upvotes: 1

David Jacquel

Reputation: 52829

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.

Upvotes: 78

Boris Burkov

Reputation: 14506

The answer by David Jacquel is awesome.

But if you're trying to serve your whole SPA personal blog from the /dist or /build folder of GitHub Pages as I do, there's a beautiful dirty hack by Raphael Pedicini.

He suggests that you create a proxy index.html page and custom 404.html page. If your user enters the direct URL of a subpage, e.g. https://example.github.io/blog/, the GitHub Pages server will serve 404.html with scripts that pass the URL as a set of parameters to a proxy index.html, which launches the SPA.

I won't duplicate his code here, as it very well might change over time.

Upvotes: 5

Chen Pang

Reputation: 1388

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

Upvotes: 9

Agustín Amenábar Larraín

Reputation: 593

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.

Upvotes: 17

Ishan Khare

Reputation: 1767

Try transferring your index.html file and all its dependencies into a new repository and then use that repository as a sub-module in you current repository. Currently GitHub Pages expects to find an index.html file in the root of your repository which it can't.

For example, let’s say your current repo is 'test'. You create anew repository say, 'website', transfer your .html and other files which are required to the 'website' repository. Now you need to use 'website' repository as a sub-module inside the 'test' repository.

Mote: in the above schema you only need to use the 'gh-pages' branch-name in your 'website' repository while 'test' can still retain the master branch.

A little example tutorial on Git submodules.

Upvotes: 1

Evandro Coan

Reputation: 9485

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

Create the file .nojekyll in the root of your gh-pages branch
Make sure you removed .png, .html, and similars from your .gitignore file

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:

Upvotes: 5

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

Answers (10)

Related Questions