https://github.com/typst-community/setup-typst
📑 Install Typst for use in GitHub Actions
https://github.com/typst-community/setup-typst
action compiler github-actions installer markup typesetting typst
Last synced: 3 months ago
JSON representation
📑 Install Typst for use in GitHub Actions
- Host: GitHub
- URL: https://github.com/typst-community/setup-typst
- Owner: typst-community
- License: mit
- Created: 2023-04-09T06:22:39.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-11T13:36:40.000Z (over 2 years ago)
- Last Synced: 2024-10-29T11:39:17.752Z (over 1 year ago)
- Topics: action, compiler, github-actions, installer, markup, typesetting, typst
- Language: JavaScript
- Homepage: https://github.com/marketplace/actions/setup-typst
- Size: 979 KB
- Stars: 113
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-typst - setup-typst - đź“‘ Install Typst for use in GitHub Actions (Integrations & Tools / CI/CD)
README
English | 简体ä¸ć–‡
# Setup Typst
This action provides the following functionality for GitHub Actions users:
- **Installing** a version of [Typst] and adding it to the PATH
- **Caching** [packages] dependencies
- **Downloading** ZIP archives as packages
```yaml
- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf
```
## Usage
### Basic Usage
```yaml
name: Render paper.pdf
on: push
jobs:
render-paper:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: typst-community/setup-typst@v5
# 🎉 Now Typst is installed!
- run: typst compile paper.typ paper.pdf
```
### Inputs
#### Installing A Typst Version
- **`typst-version`:** Version range or exact version of Typst to use, using SemVer's version range syntax. Uses the latest version if unset.
- **`allow-prereleases`:** When `true`, a version range including `latest` passed to `typst-version` input will match prerelease versions.
**`executable-name`:** Used to specify the executable file name of Typst.
```yaml
# Example 1
- uses: typst-community/setup-typst@v5
with:
typst-version: ^0.14.0
# Example 2
- uses: typst-community/setup-typst@v5
with:
typst-version: 0.14.0-rc1
allow-prereleases: true
# Example 3
- uses: typst-community/setup-typst@v5
with:
executable-name: typst-latest
```
> [!TIP]
>
> - `executable-name` defaults to `typst`.
> - A Typst executable named `typst-${version}` is always kept.
> - For Windows, there is no need to include the executable file extension `.exe` in the parameters.
> - Multiple distinct `executable-name` values can be set for the same Typst version.
> - Setting the same `executable-name` (including the default `typst`) for different Typst versions is **not recommended**, as it may lead to version management confusion.
#### Installing Multiple Typst Versions
**`typst-versions-map`:** Used to specify a JSON map of executable names to Typst version configurations, for installing multiple Typst versions at once. Each value is an object with a required `version` field and an optional `allowPrerelease` field.
> [!NOTE]
>
> When `typst-versions-map` is set, `typst-version` and `executable-name` are **ignored**. The `allow-prereleases` input is used as the **default value** for all entries in the map, but can be **overridden** by `allowPrerelease` in each individual config object.
```yaml
- uses: typst-community/setup-typst@v5
with:
typst-versions-map: |
{
"typst-latest": {"version": "latest"},
"typst-013": {
"version": "v0.13",
"allowPrerelease": true
}
}
```
#### Managing Packages with Cache
**`cache-dependency-path`:** Used to specify the path to a Typst file containing lines of `import` keyword.
```yaml
# Example workflow YAML file
- uses: typst-community/setup-typst@v5
with:
cache-dependency-path: requirements.typ
```
```typst
// Example Typst file (requirements.typ)
#import "@preview/example:0.1.0": *
```
#### ZIP Archive Packages Management
- **`zip-packages`:** Used to specify the path to a JSON file containing names and ZIP archive URLs of packages.
- **`cache-local-packages`:** When `true`, local packages set by `zip-packages` will be cached independently of `@preview` packages.
```yaml
# Example workflow YAML file
- uses: typst-community/setup-typst@v5
with:
zip-packages: requirements.json
cache-local-packages: true
```
```js
// Example JSON file (requirements.json)
{
"preview": {
"algorithmic": "https://github.com/typst-community/typst-algorithmic/archive/refs/tags/v1.0.0.zip"
},
"local": {
"glossarium": "https://github.com/typst-community/glossarium/archive/refs/tags/v0.5.7.zip"
}
}
```
> [!TIP]
>
> - For links to download GitHub repositories, please refer to [_Downloading source code archives_].
> - The supported namespaces are only `local` and `preview`.
> - The SemVer versions of packages are read from its `typst.toml`.
#### Token
**`token`:** The token used to authenticate when fetching Typst distributions from [typst/typst]. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting.
### Integration with Other Actions
#### Uploading Artifacts
If you require storing and sharing data from a workflow, you can use [artifacts].
```yaml
- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf
- uses: actions/upload-artifact@v6
with:
name: paper
path: paper.pdf
```
#### Installing Fonts with Fontist
If you require installing fonts in GitHub Actions runner, you can use [Fontist].
```yaml
- uses: fontist/setup-fontist@v2
- run: fontist install "Fira Code"
- uses: typst-community/setup-typst@v5
- run: typst compile paper.typ paper.pdf --font-path ~/.fontist/fonts
```
## Development Guide
### Prerequisites
Setup Typst uses TypeScript for development, so you'll need Node.js 20 and npm to develop the action.
### Initial Setup
You can clone the repository with the help of Git and use `npm ci` to install dependencies.
### Building
The action uses TypeScript for development and [ncc] to compile and bundle everything into a single JavaScript file for distribution.
To build the action, run `npm run build`. This command compiles the TypeScript code from `src/main.ts` and bundles it with all dependencies into the `dist/main.js` file.
You can also use `npm run lint` to run type checking and format code with `npm run format`.
### Testing
The repository uses GitHub Actions for continuous integration testing. The workflow automatically runs on pull requests and pushes to the main branch.
[Typst]: https://typst.app/
[typst/typst]: https://github.com/typst/typst
[packages]: https://github.com/typst/packages
[_Downloading source code archives_]: https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives
[artifacts]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow
[Fontist]: https://www.fontist.org/
[ncc]: https://github.com/vercel/ncc