Continuous build and publishing

You can build and publish the website automatically on push using GitHub Pages and GitHub Actions. Here's our recommendation:

.github/workflows/deploy-docs.yml

name: Deploy docs
on: [push, pull_request]
jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - name: Download source
        uses: actions/checkout@v3
      - name: Install Crystal
        uses: oprypin/install-crystal@v1
      - name: Install Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install Python libs
        run: pip install --no-deps -r requirements.txt
      - name: Install Crystal libs
        run: shards install
      - name: Build site
        run: mkdocs build
      - name: Deploy to gh-pages
        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
        run: mkdocs gh-deploy --force

Why configure like this

• Do not disable the workflow for non-master branches or pull requests. It is nice to ensure that the site builds (there can be errors!), instead at the bottom we prevent only the actual deploy action from being executed on non-master/non-pushes.
• Dependencies are installed from requirements.txt. Make sure you've populated it.

Tip

You can freely have a "dev" branch for working on docs that aren't ready for release yet. Then just merge it into the main one when ready.

Tip

Your docs don't have to be in the same repository as the main code. In fact, the doc site can span several projects! See "Multi-repo setup" in Showcase.