GitHub Pages
============

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

`GitHub Pages <https://pages.github.com/>`_ 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 <https://jekyllrb.com/>`_
(which turns `Markdown <https://www.markdownguide.org/>`_ 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: 

.. code-block:: python

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

Deploy with ABlog from a Windows command prompt:

.. code-block:: bat

    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