How to publish ExDocs on GitHub Pages

GitHub Pages allows you to publish static files, but it doesn't allow you to generate these. This is a problem if you want to generate ExDocs for a private package or generate a static website with a web framework like Angular.

The only way to have static files published on GitHub Pages is to put them on the repo, either in /docs or in a branch named gh-pages. Let's do this using GitHub Actions.

SSH key

Generating a new SSH key will allow you to push change to your Git repository from a GitHub Action. We'll use this to generate ExDocs and push them whenever there's a push on master.

ssh-keygen -t ed25519 -C "gh-pages"

Deploy key

A deploy key is an SSH key that grants access to a single repository. GitHub attaches the public part of the key directly to your repository instead of a personal user account, and the private part of the key remains on your server.

Add the public key to the Deploy keys in /settings/keys.

Action secrets

Secrets are environment variables that are encrypted. Anyone with
collaborator access to this repository can use these secrets for Actions.

Add the private key to the Repository secrets in /settings/secrets/actions.

GitHub Action

With this setup, your GitHub Actions now have the ability to modify the repository. Depending on weather you want to put the docs in /docs or in gh-pages, the steps will be very similar.

Using a GitHub Action, we'll execute these steps:

1. Generate ExDocs in /doc
2. Initialize a Git repository in /doc
3. Link this new local repo to your repository
4. Force push the whole directory to gh-pages

Here's an example of the GitHub Actions file.

name: GitHub Pages

on:
  push:
    branches: [master]

jobs:
  build:
    name: Push to gh-pages
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Set up Elixir
        uses: erlef/setup-beam@988e02bfe678367a02564f65ca2e37726dc0268f
        with:
          elixir-version: "1.13.3" # Define the elixir version [required]
          otp-version: "24" # Define the OTP version [required]
      - name: Restore dependencies cache
        uses: actions/cache@v2
        with:
          path: deps
          key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
          restore-keys: ${{ runner.os }}-mix-
      - name: Install dependencies
        run: mix deps.get

      - name: Force push to gh-pages
        run: |
          # Generate docs
          mix docs

          # Setup
          cd doc
          git init --initial-branch gh-pages
          git remote add origin $ORIGIN
          git config user.name "$NAME"
          git config user.email "$EMAIL"
          eval `ssh-agent -s`
          ssh-add - <<< '${{ secrets.GH_PAGES_SSH }}'

          # Push
          git add .
          git commit -m "mix docs"
          git push --set-upstream origin gh-pages -f

In this file, you'll have to replace the variables $NAME, $EMAIL and $ORIGIN.

Once it's commited to master, the GitHub Pages will be automatically deployed!