Skip to content

summerBreeze03/typst-doc-cn.github.io

 
 

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 包 jinja2.

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

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

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

About

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

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 61.8%
  • HTML 27.7%
  • Typst 6.7%
  • CSS 1.9%
  • JavaScript 0.8%
  • Jinja 0.8%
  • Other 0.3%