Typst Project Template with Automated Releases

This repository serves as a template for creating documents with Typst, a modern, markup-based typesetting system. It includes a pre-configured GitHub Actions workflow that automatically compiles your document and creates a GitHub Release whenever you push a new version tag.

Features

• Automated PDF Compilation: Automatically compiles main.typ into main.pdf on every run.
• Dependency Caching: Uses typst-community/setup-typst to cache dependencies listed in requirements.typ, speeding up subsequent builds.
• Automatic Releases: Creates a new GitHub Release with the compiled PDF attached whenever a tag matching the v*.*.* pattern is pushed.
• Manual Workflow Trigger: Allows for manual builds directly from the GitHub Actions tab, perfect for testing changes without creating a release.

File Structure

.
├── .github/
│   └── workflows/
│       └── release.yml     # The GitHub Actions workflow definition.
├── main.typ                # Your main Typst document entry point.
├── requirements.typ        # List your Typst package dependencies here.
├── bibliography.yml        # A sample bibliography file (if needed).
└── README.md               # This file.

• main.typ: This is the heart of your document. All your content should start here.
• requirements.typ: If your project uses external Typst packages, you should specify them here. The workflow will automatically fetch and cache them. For example:

#import "@preview/fletcher:0.5.8"
#import "@preview/physica:0.9.5"

• .github/workflows/release.yml: This file defines the Continuous Integration/Continuous Deployment (CI/CD) pipeline. See the "Workflow Breakdown" section below for a detailed explanation.

How to Use This Template

There are two primary ways to use the automation provided in this template.

Method 1: Creating a Release/Tag (Recommended)

This is the standard way to publish a new version of your document. The workflow will automatically create a GitHub Release and attach your compiled PDF.

1. Commit Your Changes: Make sure all your latest changes to the .typ files are committed to your main branch.

git add .
git commit -m "Finalize version 1.0.0"

2. Tag the Version: Create a new Git tag that follows the semantic versioning format (e.g., v1.0.0, v1.2.3).

git tag v1.0.0

3. Push the Tag: Push your commits and the new tag to GitHub.

git push origin v1.0.0

Once the tag is pushed, the "Release" workflow will automatically start. It will compile main.typ and create a new release on your repository's "Releases" page, named v1.0.0 — <current_date>, with main.pdf attached as an asset.

Method 2: Manual Build for Testing

If you want to compile the PDF to see the result without creating a public release, you can trigger the workflow manually.

1. Navigate to the Actions tab in your GitHub repository.
2. In the left sidebar, click on the Release workflow.
3. You will see a message: "This workflow has a workflow_dispatch event trigger." Click the Run workflow dropdown button.
4. You will be prompted to enter a version string. This is for informational purposes in the run log; you can enter any value (e.g., test-build).
5. Click the green Run workflow button.

The workflow will run, but the final "Release" step will be skipped. You can download the compiled main.pdf from the "Artifacts" section on the summary page for that workflow run.

Workflow Breakdown (release.yml)

The automation is powered by the .github/workflows/release.yml file. Here is a step-by-step explanation of what it does.

Triggers

The workflow is triggered by two events:

1. push: tags:: Runs automatically when a tag matching the pattern v[0-9]+.[0-9]+.[0-9]+* is pushed.
2. workflow_dispatch:: Allows the manual execution described above.

Permissions

• contents: write: This is essential. It grants the workflow permission to create GitHub Releases and upload files (artifacts) to them.

Job: build

The workflow consists of a single job named build that runs on an ubuntu-latest virtual machine.

• actions/checkout@v4: This step checks out your repository's code so the workflow can access your .typ files.

• typst-community/setup-typst@v4: This community action installs the specified version of Typst (0.13). The cache-dependency-path key is configured to look at requirements.typ, enabling caching of Typst packages to make future runs faster.

• Compile Typst files: A simple shell command that runs the Typst compiler, taking main.typ as input and producing main.pdf.

typst compile main.typ main.pdf

• Upload PDF file: This step uses actions/upload-artifact@v4 to save the generated main.pdf as a workflow artifact. This is useful for every run, as it allows you to download the PDF even if a release isn't created.

• Get current date: Creates a timestamp that is used in the release name for uniqueness.

• softprops/action-gh-release@v1: This is the final step that creates the release.

  • if: github.ref_type == 'tag': This crucial condition ensures this step only runs if the workflow was triggered by a tag. It is skipped during manual workflow_dispatch runs.
  • name: "${{ github.ref_name }} — ${{ env.DATE }}": Sets the release title to the tag name (e.g., v1.0.0) plus the date.
  • files: main.pdf: Attaches the compiled main.pdf to the release.

Customization

• Typst Version: To use a different version of Typst, simply change the typst-version in the release.yml file.
• Main File: If your main Typst file is not named main.typ, you will need to update the Compile Typst files and Release steps in release.yml.
• Release Assets: You can add more files to the release (e.g., a ZIP of the source code) by modifying the files: list in the Release step.