Skip to content

Getting started with GitHub Pages

Jump to bottom
Felix Fontein edited this page Nov 23, 2022 · 3 revisions

Using GitHub Pages as a publish target

There is a shared workflow for publishing to GitHub Pages.

This is intended to be an opinionated, specific way of doing so that supports multiple simultaneous docs builds within a single GitHub Pages site, not a general workflow to have a high degree of customizability.

The reason for that, is that the bulk of the "work" of publishing to GH pages is handled by a single action, peaceiris/actions-gh-pages, which can be used directly if you wish to do something simpler or more custom.

Alternatively, "publishing" to GitHub Pages is done via commit and push, so if you want to skip the action you can similarly put something together using git commands.

Or this workflow can have the destination-dir overridden, which is really where our convention is applied.

About the convention used

When destination-dir is not set, this workflow puts docs into sub-directories in the published site based on the event:

  • for a pull request, the site is published to /pr/XX where XX is the PR number, for example: /pr/123
  • for a push to a branch, the site is published to /branch/NAME, for example: /branch/main or /branch/stable-3
  • for a push to a tag, the site is published to /tag/TAG, for example: /tag/3.21.7

Since the consumer of the workflow completely controls the triggers of their calling workflow, anyone who wants to limit which sites get published can do so by limiting the workflow triggers (triggering on only PRs or pushes, limiting the branches and tags, etc.); this does not need customization in the workflow.

Setting up GitHub Pages for the first time

If your repository already has GitHub Pages set up, it might be best to post a Q&A Discussion first if you have anything existing you would like to preserve, or if you have a specific way in mind that deviates from what is described here.

Enabling GitHub Pages

The shared workflow currently only works when Pages is set up on the gh-pages branch.

Setting up the branch

To start, we will create an orphan branch with no content:

git switch --orphan gh-pages

This should create a completely empty branch. Some files that were .gitignored in your repository may show up; be sure not to add or commit those.

Now we need to push the branch, but to do so there needs to be at least one commit.

Since the root of our Pages site will not actually host the collection documentation, it makes sense to redirect the root to the branches/main/ path (which will not exist yet but that is ok). To do that, create a new file index.html with this content:

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="refresh" content="0;url=https://owner.github.io/repository/branch/main/" />
    </head>
    <body>
        <h1>
            The page has been moved to <a href="https://owner.github.io/repository/branch/main/">https://owner.github.io/repository/branch/main/</a>
        </h1>
    </body>
</html>

The URL used will depend on your Pages configuration. Typically, the domain is owner.github.io where owner is your user name or organization. Collections under the ansible-collection organization for example will use ansible-collectons.github.io.

The repository portion of the URL is the name of the repository (without the owner). For many collections this is namespace.collection.

So for the ansible-collections/community.general repository, the base URL is https://ansible-collections.github.io/community.general.

In this file, we ensure that the root of that site redirects to the docs for the main branch.

If the redirect is not desired that is ok too, but we still need to commit something to push the branch. In that case, we can use the .nojekyll file which will be required anyway (the workflow already ensures this file exists when it runs, but it does not hurt to create separately).

touch .nojekyll

With either (or both) files created, add and commit them, and then push (adjust commands as needed):

git add index.html
git commit -m 'redirect root to branches/main'
git push -u upstream gh-pages

If you clone your repo directly push to origin, or adjust as needed.

Enabling Pages

If you have permissions to enable Pages, then pushing the branch may have been enough to enable Pages automatically. A new GitHub Actions workflow will have triggered to take care of building and publishing pages (this is not a workflow you can edit, but you can watch its progress along with other workflows).

To check for sure, visit the repository settings and click Pages on the left side navigation.

Enabling Pages is done by choosing a branch and a folder. The gh-pages branch should be chosen, with / (root) as the folder.

image

Using the workflow

With GitHub Pages enabled, the workflows do the rest of the work of rendering docs and pushing them to gh-pages branch for publishing.

You can always switch to the gh-pages branch, pull it down, and edit or change anything you like.

Clone this wiki locally