Publish example PDFs using GitHub Pages

Showcase
,
1

When creating a package or template, an alternative to including example PDFs within the repository can be to use GitHub Pages.

Advantages:

  • No need to include PDFs (= binary files) in the Git repository
  • Can automate creation of PDFs using GitHub Actions
  • Directly view PDFs with the built-in PDF viewer of the browser[1]

Disadvantages:

  • PDFs are not versioned; you cannot obtain an older version of the PDF, respectively you have to manually compile it yourself

Setup:

  1. Configure your repository to publish GitHub Pages from a GitHub Actions workflow
  2. Create a GitHub Actions workflow for building the example and publishing it (see also actions/upload-pages-artifact).
    For example:
    .github/workflows/publish-examples.yml
    # Publish GitHub Pages site consisting of compiled example PDFs
name: Publish example

on:
  push:
    branches:
      - main

# Overwritten by the individual jobs
permissions: {}

jobs:
  build-site:
    runs-on: ubuntu-latest
    permissions:
      contents: read #  to fetch code (actions/checkout)

    steps:
    - uses: actions/checkout@v5
    - uses: typst-community/setup-typst@v4
      with:
        typst-version: 0.13.1

    - name: Create output dir
      # Note: `github-pages-temp` should not exist yet
      run: mkdir github-pages-temp

    - name: Build example
      run: typst compile example.typ github-pages-temp/example.pdf

    - name: Upload site files as artifact
      id: deployment
      uses: actions/upload-pages-artifact@v4
      with:
        path: github-pages-temp

  # See https://github.com/actions/deploy-pages
  deploy-site:
    needs: build-site

    permissions:
      pages: write
      id-token: write

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
  3. Access the site at https://<user>.github.io/<repository>/<file> (and link to it for example from your README), e.g. https://octocat.github.io/my-typst-package/example.pdf

Alternatively you can configure the workflow to only run when creating a GitHub release.

You can also use this together with the tidy package to generate API documentation for your package and deploy it to GitHub Pages.

There are some limitations for GitHub Pages, but for this use case that should probably not be an issue.

I know this is not really a novel approach, but it seems this hasn’t been mentioned here before, so maybe it is useful for some of you.

What do you think? Are you aware of any other advantages / disadvantages of this approach?

  1. This is better than for PDFs within a Git repository, where GitHub seems to use a custom PDF viewer which provides less functionality than the built-in one of the browser; or you would have to download the PDF first ↩︎

4 Likes
2

Making the PDF manual easily accessible if it is the main documentation is super important!

Additional advantage: by using GH Actions, you can’t forget to update the PDF when you change the inputs (including your source code if using tidy.

I’m currently trying out shiroa, which would also make it easier to view the manual on the web, but I still have to integrate it with tidy to work with my existing documentation. I’ll probably make a separate showcase about that at some point unless someone else beats me to it :slight_smile:

fyi, if you add ?raw=1 to the URL of your PDF manuals, Github will redirect you to https://raw.githubusercontent.com/, where you can view the PDF directly. I use links like that in all of my packages’ READMEs.

4 Likes
3

Note that when publishing to Typst Universe, then using GitHub Pages might not be suitable: