From 6e36c3c118e1ed4079f64374499831b48f715ed6 Mon Sep 17 00:00:00 2001 From: yusancky Date: Sun, 11 Feb 2024 21:16:05 +0800 Subject: [PATCH] Update README & Create Chinese README (#20) --- .github/workflows/test-action.yml | 4 +- README.md | 77 +++++++++++++++--------- README_zh-Hans-CN.md | 98 +++++++++++++++++++++++++++++++ action.yml | 23 ++++---- 4 files changed, 160 insertions(+), 42 deletions(-) create mode 100644 README_zh-Hans-CN.md diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml index 07c283f..27da791 100644 --- a/.github/workflows/test-action.yml +++ b/.github/workflows/test-action.yml @@ -4,14 +4,14 @@ on: branches: "main" paths-ignore: - .gitignore - - README.md + - README*.md - LICENSE - .github/** - "!.github/workflows/test-action.yml" pull_request: paths-ignore: - .gitignore - - README.md + - README*.md - LICENSE - .github/** - "!.github/workflows/test-action.yml" diff --git a/README.md b/README.md index 3e5c24d..a02d291 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Setup Typst -📑 Install Typst for GitHub Actions \ -⚡ Caches Typst installation \ -📦 Caches [packages](https://github.com/typst/packages) as dependencies +This action provides the following functionality for GitHub Actions users: +- Installing a version of Typst and adding it to the PATH +- Optionally caching [packages](https://github.com/typst/packages) dependencies
-```yml +```yaml - uses: typst-community/setup-typst@v3 - run: typst compile paper.typ paper.pdf ``` @@ -18,7 +18,9 @@ ![GitHub Actions](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+Actions&color=2088FF&logo=GitHub+Actions&logoColor=FFFFFF&label=) ![GitHub](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub&color=181717&logo=GitHub&logoColor=FFFFFF&label=) -```yml +### Basic usage + +```yaml name: Render paper.pdf on: push jobs: @@ -31,34 +33,55 @@ jobs: cache-dependency-path: requirements.typ # Now Typst is installed and packages will be cached! - run: typst compile paper.typ paper.pdf - - uses: actions/upload-artifact@v4 - with: - name: paper - path: paper.pdf ``` ### Inputs -- **`typst-token`:** The GitHub token to use when pulling - versions from [typst/typst]. By default this should cover all - cases. You shouldn't have to touch this setting. +- **`typst-token`:** The GitHub token to use when pulling versions from + [typst/typst]. By default this should cover all cases. You shouldn't have to + touch this setting. +- **`typst-version`:** The version of Typst to install. This can be an exact + version like `0.10.0` or a semver range like `0.10` or `0.x`. You can also + specify `latest` to always use the latest version. The default is `latest`. +- **`cache-dependency-path`:** Used to specify the path to dependency file. + Supports a Typst file with lines of `import` keyword. + +### Outputs -- **`typst-version`:** The version of Typst to install. This can - be an exact version like `0.10.0` or a semver range like - `0.10` or `0.x`. You can also specify `latest` to always use - the latest version. The default is `latest`. +- **`typst-version`:** The version of Typst that was installed. This will be + something like `0.10.0` or similar. +- **`cache-hit`:** Whether or not Typst was restored from the runner's cache or + download anew. -- **`cache-dependency-path`:** Used to specify the path to - dependency file. Supports a Typst file with lines of - 'import' keyword. +### Custom combinations -### Outputs +#### Uploading workflow artifact + +```yaml +- uses: typst-community/setup-typst@v3 + with: + cache-dependency-path: requirements.typ +- run: typst compile paper.typ paper.pdf +- uses: actions/upload-artifact@v4 + with: + name: paper + path: paper.pdf +``` -- **`typst-version`:** The version of `typst` that was - installed. This will be something like `0.10.0` or similar. +#### Expanding font support with Fontist -- **`cache-hit`:** Whether or not Typst was restored from the - runner's cache or download anew. +If your tasks require extending beyond the set of fonts in GitHub Actions runner, +you can employ the Fontist to facilitate custom font installations. Here's an +example showcasing how to use [fontist/setup-fontist] to add new fonts: + +```yaml +- uses: fontist/setup-fontist@v2 +- run: fontist install "Fira Code" +- uses: typst-community/setup-typst@v3 + with: + cache-dependency-path: requirements.typ +- run: typst compile paper.typ paper.pdf --font-path ~/.fontist/fonts +``` ## Development @@ -66,8 +89,8 @@ jobs: **How do I test my changes?** -Open a draft Pull Request and some magic GitHub Actions will run -to test the action. +Open a draft Pull Request and some magic GitHub Actions will run to test the +action. -[typst]: https://typst.app/ +[Typst]: https://typst.app/ [typst/typst]: https://github.com/typst/typst diff --git a/README_zh-Hans-CN.md b/README_zh-Hans-CN.md new file mode 100644 index 0000000..2118298 --- /dev/null +++ b/README_zh-Hans-CN.md @@ -0,0 +1,98 @@ +

+ English | 简体中文 +

+ +# Setup Typst + +此操作为 GitHub Actions 用户提供以下功能： +- 安装给定版本的 Typst 并将其加入 PATH +- 可选地将 [第三方包](https://github.com/typst/packages) 依赖缓存 + +
+ +```yaml +- uses: typst-community/setup-typst@v3 +- run: typst compile paper.typ paper.pdf +``` + +
+ +## 用法 + +![GitHub Actions](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+Actions&color=2088FF&logo=GitHub+Actions&logoColor=FFFFFF&label=) +![GitHub](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub&color=181717&logo=GitHub&logoColor=FFFFFF&label=) + +### 基本用法 + +```yaml +name: Render paper.pdf +on: push +jobs: + render-paper: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: typst-community/setup-typst@v3 + with: + cache-dependency-path: requirements.typ + # Typst 被安装，且第三方包将被缓存！ + - run: typst compile paper.typ paper.pdf +``` + +### 输入 + +- **`typst-token`:** 当从 [typst/typst] 拉取版本时使用的 GitHub 令牌。默认情况下，这应 + 该涵盖全部情况。你通常无需修改此项。 + +- **`typst-version`:** 需要安装的 Typst 的版本。它可以是一个确定的版本号如 `0.10.0` 或 + 语义化版本号如 `0.10` 和 `0.x`。你也可以使用 `latest` 使用最新版本的 Typst。默认值为 + `latest`。 + +- **`cache-dependency-path`:** 第三方包依赖列表文件的文件名。该文件应该是一个含有 + `import` 关键字的 Typst 文件。 + +### 输出 + +- **`typst-version`:** 安装的 Typst 的版本。它的格式应该类似 `0.10.0`。 + +- **`cache-hit`:** Typst 是否存缓存下载。 + +### 自定义组合 + +#### 上传工作流构件 + +```yaml +- uses: typst-community/setup-typst@v3 + with: + cache-dependency-path: requirements.typ +- run: typst compile paper.typ paper.pdf +- uses: actions/upload-artifact@v4 + with: + name: paper + path: paper.pdf +``` + +#### 使用 Fontist 拓展字体支持 + +如需为 GitHub Actions 运行器拓展字体库，可使用 Fontist 进行自定义字体安装。以下是使用 +[fontist/setup-fontist] 添加新字体的范例： + +```yaml +- uses: fontist/setup-fontist@v2 +- run: fontist install "Fira Code" +- uses: typst-community/setup-typst@v3 + with: + cache-dependency-path: requirements.typ +- run: typst compile paper.typ paper.pdf --font-path ~/.fontist/fonts +``` + +## 开发 + +![Node.js](https://img.shields.io/static/v1?style=for-the-badge&message=Node.js&color=339933&logo=Node.js&logoColor=FFFFFF&label=) + +**我应该如何测试我的贡献？** + +开启一个草稿拉取请求，GitHub Actions 测试项将在被管理员的许可后运行。 + +[Typst]: https://typst.app/ +[typst/typst]: https://github.com/typst/typst diff --git a/action.yml b/action.yml index 0ee8888..e9ebc8d 100644 --- a/action.yml +++ b/action.yml @@ -8,33 +8,30 @@ branding: inputs: typst-token: description: > - The GitHub token to use when pulling versions from - typst/typst. By default this should cover all cases. - You shouldn't have to touch this setting. + The GitHub token to use when pulling versions from typst/typst. By default + this should cover all cases. You shouldn't have to touch this setting. default: ${{ github.server_url == 'https://github.com' && github.token || '' }} typst-version: description: > - The version of Typst to install. This can be an exact - version like '0.10.0' or a semver range like '0.10' or - '0.x'. You can also specify 'latest' to always use the - latest version. The default is 'latest'. + The version of Typst to install. This can be an exact version like '0.10.0' + or a semver range like '0.10' or '0.x'. You can also specify 'latest' to + always use the latest version. The default is 'latest'. default: latest cache-dependency-path: description: > - Used to specify the path to dependency file. Supports a - Typst file with lines of 'import' keyword. + Used to specify the path to dependency file. Supports a Typst file with + lines of 'import' keyword. required: false outputs: typst-version: description: > - The version of 'typst' that was installed. This will be - something like '0.10.0' or similar. + The version of Typst that was installed. This will be something like + '0.10.0' or similar. cache-hit: description: > - Whether or not Typst was restored from the runner's cache - or download anew. + Whether or not Typst was restored from the runner's cache or download anew. runs: using: node20