GitHub Pages

https://docs.github.com/en/pages/quickstart

GitHub Pages can be used to host a static website for free.

GitHub Pages serves static files from a repository and, by default, runs them through Jekyll (which turns Markdown into HTML). Sphinx already produces finished HTML, so Jekyll only gets in the way.

Warning

It is possible to bypass Jekyll processing on GitHub Pages by creating a file named .nojekyll in the root of your pages repo and pushing it to GitHub.

This should only be necessary if your site uses files or directories that start with underscores since Jekyll considers these to be special resources and does not copy them to the final site.

For Sphinx docs to render correctly on GitHub Pages:

# conf.py: creates .nojekyll so _static and _sources are published
extensions = [
    ...
    'sphinx.ext.githubpages',
]

Deploy with ABlog from a Windows command prompt:

set GITHUB_PAGES=samkhalilian
set WEBSITE=_build/html
set REPODIR=Z:/samkhalilian.github.io
set GITHUB_BRANCH=main
ablog deploy -w %WEBSITE% -p %REPODIR% -g %GITHUB_PAGES% --github-branch %GITHUB_BRANCH% --github-ssh

SSH is preferred. --github-token also works, but read the token from an environment variable you set outside the docs and never commit it.

Windows bug fix

On Windows, ablog deploy can fail with “command line is too long”. The workaround is a local patch around line 435 of ablog/commands.py in the virtual environment’s site-packages; it must be reapplied after upgrading ABlog.

Custom Domain

https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site