Update README & Create Chinese README (#20)

typst-community · Feb 11, 2024 · 6e36c3c · 6e36c3c
1 parent ebe8708
commit 6e36c3c
Show file tree

Hide file tree

Showing 4 changed files with 160 additions and 42 deletions.
diff --git 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
@@ -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
 
 <table align=center><td>
 
-```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,43 +33,64 @@ 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
 
 ![Node.js](https://img.shields.io/static/v1?style=for-the-badge&message=Node.js&color=339933&logo=Node.js&logoColor=FFFFFF&label=)
 
 **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
@@ -0,0 +1,98 @@
+<p align=center>
+  <a href="https://github.com/typst-community/setup-typst/blob/main/README.md" hreflang="en" lang="en">English</a> | <b>简体中文</b>
+</p>
+
+# Setup Typst
+
+此操作为 GitHub Actions 用户提供以下功能：
+- 安装给定版本的 Typst 并将其加入 PATH
+- 可选地将 [第三方包](https://github.com/typst/packages) 依赖缓存
+
+<table align=center><td>
+
+```yaml
+- uses: typst-community/setup-typst@v3
+- run: typst compile paper.typ paper.pdf
+```
+
+</table>
+
+## 用法
+
+![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
@@ -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