Guide: Preview typst.app/docs (of your PR) on netlify

Showcase
,
1

Introduction

:stuck_out_tongue_winking_eye: I'm really fed up with this damn document

If you’ve managed to submit a PR improving typst.app/docs, and you want to verify that markdown and code examples are rendered as expected, then here’s a guide to preview your PR on netlify.

  • No prior knowledge or local installation of rust / node.js is required.
  • A basic idea of git is necessary, such as how to create a new branch and what it means.

Example result

Current version on typst.app/docs

figure.kind
figure.kind1138×805 112 KB

My edit

figure.kind
figure.kind1359×662 152 KB

Preview of my edit

figure.kind
figure.kind896×726 84.9 KB

How to preview Typst Documentation (of your PR) on netlify

  1. Create a new branch (e.g., netlify) from your PR.

  2. Create netlify.toml at the root directory, and paste the following.

    [build]
command = "bash ./netlify-build-docs.sh"
publish = "website/dist"

  3. Create netlify-build-docs.sh next to it, and paste the following.

    #!/usr/bin/env bash
set -euxo pipefail

# 1. Install tools

curl -sS https://webi.sh/sd | sh && source ~/.config/envman/PATH.env
curl https://mise.run | sh

# 2. Clone typst-jp.github.io

# Tested against https://github.com/typst-jp/typst-jp.github.io/commit/f588f0d53dbb39225739fa7faeecb33d9b4b055b
git clone --depth 1 --no-checkout --filter=tree:0 https://github.com/typst-jp/typst-jp.github.io ../jp
cd ../jp
git sparse-checkout init
git sparse-checkout set website/ tsconfig.json package.json bun.lockb .mise.toml
git switch main
cd -

# 3. Move files from typst-jp

cat << EOF >> .gitignore
# From typst-jp
/website/
/tsconfig.json
/package.json
/bun.lockb
/.mise.toml

# Generated
/assets/docs/
/assets/docs.json
EOF

# This `cp -r` cannot be replaced with `ln -s`, because there will be a symlink created in website/public
cp -r ../jp/website/ .
ln -s ../jp/{tsconfig.json,package.json,bun.lockb} .
cp ../jp/.mise.toml .

# The rust edition has been bumped to 2024 in https://github.com/typst/typst/pull/6637
sd --fixed-strings \
    'rust = "1.83.0"' \
    'rust = "1.88.0"' \
    .mise.toml

# Use canonical typst-docs for `mise run generate-docs`
sd --fixed-strings \
    'run = "cargo test --package typst-docs --lib -- tests::test_docs --exact --nocapture"' \
    'run = "cargo run --package typst-docs -- --assets-dir assets/docs --out-file assets/docs.json --base /docs/"' \
    .mise.toml
mkdir -p website/public/docs
sd --fixed-strings \
    'const publicAssetsDocsPath = resolve(__dirname, "./public/assets/docs/");' \
    'const publicAssetsDocsPath = resolve(__dirname, "./public/docs/assets/");' \
    website/vite.config.ts

# Replace the typst version with the commit hash
sd --fixed-strings \
    '"version": "0.13.1"' \
    "\"version\": \"dev.$(git rev-parse --short HEAD)\"" \
    website/package.json

# 4. Build

mise trust
mise install
mise run generate

# For debugging:
cp assets/docs.json website/dist/

# For dev: Run `mise run dev`
# For deploy: Upload website/dist

  4. Import the branch to Netlify.

    Step-by-step screenshots

    1. Go to app.netlify.com/start, choose GitHub, grant read permission of your repo, and select it.

      GitHub
      GitHub767×301 23.3 KB

      typst
      typst1216×398 40.9 KB

    2. In the config page, input an arbitrary project name and choose the branch you’ve just created.

      图片
      图片708×576 42.4 KB

    3. Verify that the following fields as been filled automatically, and press the Deploy [project-name] button

      图片
      图片735×361 22.5 KB

      图片
      图片378×114 4.08 KB

  5. Wait for 4–5 minutes, and the preview will be available.

    Screenshots

    图片
    图片1125×790 66.6 KB

    图片
    图片934×904 85.5 KB

Netlify free plan allows 300 minutes / month. Therefore, I suggest create a dedicated a branch for previewing, and only merge your edits to that branch when necessary.

Additional info: How it works

  1. The information of the docs are scattered throughout github.com/typst/typst.

  2. The crate typst-docs (docs/src/main.rs) scans it and generates the JSON representation of the documentation.

  3. The unofficial Japanese translation project (typst-jp.github.io) provides a front end to render that JSON into a website.

  4. I merely integrate these tools and make them applicable to general PRs.

There are other ways to use the JSON.
If you want to preview locally, I recommend GitHub - JL710/typst-mdbook-docs. It converts the JSON to plain markdown files. (In-page links will be broken, however.)

Further links

Latest version of my scripts: typst/netlify-build-docs.sh at netlify-base · YDX-2147483647/typst · GitHub.

Forum:

The official typst repo:

Community repos:

7 Likes
2

Update

I put the JSON generated by typst-docs at https://ydx-typst.netlify.app/docs.json, because I find myself keep recompiling typst and inspecting it.
It’s usefull for tasks like Find all Typst types, or Find all parameters that can take a function.

3

You may be interested by

2 Likes
4

I’ve updated the build script with latest commits in the typst-jp repo. It’s simpler thanks to works in Make the website static site generator distributable · Issue #233 · typst-jp/docs · GitHub.

However, I can’t edit my original post anymore. The script will live here:

Note that I’ve changed the base from /docs/ to /:

The URL of docs.json is not affected.

See also Best of Typst (TCDM) for alternative infrastructure of building the Typst documentation.