Skip to content

typst-doc-cn/typst-doc-cn.github.io

This branch is 43 commits ahead of, 1044 commits behind typst/typst:main.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

6eb7325 · Mar 2, 2025
Oct 8, 2024
May 9, 2024
Dec 8, 2023
Mar 2, 2025
Oct 8, 2024
Oct 8, 2024
Dec 7, 2023
Nov 24, 2023
Apr 4, 2023
Mar 27, 2023
Dec 8, 2023
Jul 2, 2023
Dec 8, 2023
Dec 8, 2023
Apr 27, 2023
Mar 18, 2023
Nov 19, 2023
Mar 28, 2024
Oct 29, 2023
Nov 17, 2023
Dec 8, 2023
Nov 4, 2022
Dec 25, 2023

Repository files navigation

Typst 中文文档网站

社区驱动的非官方 Typst 中文文档.

https://typst-doc-cn.github.io/docs/

GitHub Repo:https://github.com/typst-doc-cn/typst-doc-cn.github.io

Gitee 镜像:https://gitee.com/orangex4/typst-doc-cn.github.io

贡献

  1. Fork 仓库
  2. 更改 ./docs/src 目录下的 Markdown 文件
  3. 更改 ./docs/i18n 目录下的 Yaml 文件
  4. 如果你想为「第三方包」(packages)页面的包添加对应翻译,可以修改 ./static/assets/index2cn.json 文件
  5. 遵守翻译规范:
  6. 中英文之间添加一个空格
  7. 尽量使用中文标点符号
  8. 不确定的术语可以参考术语表或者其他页面的翻译
  9. 示例 (example) 里的英文不需要翻译成中文
  10. 发起一个 Pull Request
  11. 如果需要的话,也可以在文档的末尾处留下翻译者的名字

如果想要贡献, 并且有任何问题的话, 可以加入 QQ 群 793548390 联系 OrangeX4.

当然也可以直接尝试翻译和发起 Pull Request.

技术细节

Typst 的文档生成是与 Typst 源码紧耦合的, 具体体现在:

  1. Typst 开发者使用 Rust 写了一个 docs 模块, 文档生成的大部分工作都在这里进行;
  2. Typst 的文档是使用一种 Markdown 的方言以及 Yaml 文件生成的, docs/src 路径下的文件;
  3. docs 模块里的函数被执行后, 会动态地生成示例图片, 就像你们示例代码对应的右边的示例图片, 均为编译时生成的;
  4. 参考部分对应的大部分页面, 例如 lorem 函数, 对应的 Markdown 部分是写在 lorem 函数对应的 Rust 代码文件的注释里的, 有点像 docstring;
  5. Typst Repo 里面只有 docs 模块的代码, 没有对应的文档网页生成的代码, 那部分还没有开源;

因此我做了以下事情以生成这个 Typst 中文文档网页:

  1. 修改了 docs 模块的部分代码, 在 assets 路径下生成了一个所有文档对应的 docs.json 文件, 这个文件里面的结构相对复杂, 但是包含了生成一个文档网站的全部内容;
  2. docs.json 里面有多种类型的结构:
    1. 最简单的是 html 类型, 对应概览和教程, 以及参考的 LANGUAGE 大部分;
    2. 还有 type 类型, 对应的就是类型对应的页面;
    3. 还有 func 类型, 对应的就是函数对应的页面, 里面内容繁杂, 东西很多;
    4. 其他还有三种类型 category, funcs, symbol;
  3. 我依照官网的 HTML 和 CSS 文件, 使用 jinja2 的语法写了几个 HTML 模板, 放在 templates 路径下;
  4. 然后我写了 gen.py, 用于将 docs.json 使用模板转换为最终的 Web 网站, 放在 dist 路径下;
  5. 根据 docs.json 里的内容, 生成了 i18n 目录便于翻译;
  6. 写了一个 GitHub Action 用于将生成 dist 部署到 GitHub Pages 上.

本地生成

本地生成是非必须的, 但是它很适合你在本地查看生成的网页是否正确.

首先你需要 clone 本仓库, 并安装 cargo 工具链, 以及 Python 和 Python 包 jinja2pyyaml.

# 修改了 `./docs/src` 目录则需要运行这两行命令
cargo test --package typst-docs --lib -- tests::test_docs --exact --nocapture
# 如果只是修改 `./docs/i18n` 目录则只需要运行这行命令
python ./gen.py

最后编译得到的文件位于 ./dist.

如果你有安装 nodejs, 则你可以通过 npx serve ./dist 快速地在本地开启一个 web 静态服务器预览结果.

Releases

No releases published

Packages

No packages published

Languages

  • Rust 65.3%
  • HTML 24.1%
  • Typst 7.0%
  • CSS 1.7%
  • JavaScript 0.7%
  • Jinja 0.7%
  • Other 0.5%