GitHub Pages

GitHub Pages is the default and most supported method of serving a hexdoc book as a website.

Setup

1. In your local Git repo, run these commands to create an empty branch for GitHub Pages:

   git switch --orphan gh-pages
   git commit --allow-empty -m "Initial commit"
   git push -u origin gh-pages
   git switch -  # optional: switch back to the previous branch
2. In your GitHub repo, go to Settings > Pages.
3. In the Build and deployment section, set the following values:
   • Source: Deploy from a branch
   • Branch: gh-pages
   • Folder: /docs
4. Save your changes.

note

Making changes to these settings will immediately trigger the built-in pages-build-deployment workflow. If you haven't yet deployed your book to the gh-pages branch, this workflow will fail since the docs/ folder does not exist. This failure is expected at this point - you can safely ignore it.

Deploying with GitHub Actions

You can use the hexdoc-dev/hexdoc/.github/workflows/hexdoc.yml reusable workflow to build and deploy a hexdoc book using GitHub Actions.

Try using hexdoc-mod-template to generate a sample project, or see Hex Casting for a real-world example.

Hex Addons

hexdoc-hexcasting-template is a version of hexdoc-mod-template designed specifically for creating new Hex Casting addons. It's also compatible with hexdummy.