diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b234f6 --- /dev/null +++ b/README.md @@ -0,0 +1,118 @@ +# Typst Project Template with Automated Releases + +This repository serves as a template for creating documents with [Typst](https://typst.app/), 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 + +```bash +. +├── .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: + +```typst +#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. + +```bash +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`). + +```bash +git tag v1.0.0 +``` + +3. **Push the Tag**: Push your commits and the new tag to GitHub. + +```bash git push origin main +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 — `, 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`. + +```bash +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.