clreq-gap for typst

├── scripts ├── typst-version.json ├── util.ts ├── netlify-build.sh ├── dev.ts ├── config.ts ├── patch-htmldiff.template.js ├── typst.ts ├── download_fonts.sh ├── patch-htmldiff.ts ├── build.ts ├── precompile.ts ├── generate-json-index.ts └── check_issues.ts ├── src ├── vite-env.d.ts ├── main.ts ├── anchor-highlight.ts ├── respec │ ├── mod.ts │ ├── base.override.css │ ├── language.css │ ├── structure.css │ ├── language.ts │ ├── utils.ts │ ├── sidebar.ts │ ├── structure.ts │ └── base.css ├── anchor-highlight.css ├── util.css ├── theme.ts ├── show-example.css ├── anchor-redirect.ts ├── global.css └── htmldiff-nav.ts ├── public ├── webapp-misspell.png ├── font-fallback-messy.png ├── vertical-example-modern.jpg └── vertical-example-ancient.jpg ├── .git-blame-ignore-revs ├── .github ├── dependabot.yml └── workflows │ ├── autofix.yml │ ├── pr-diff.yml │ ├── cron.yml │ ├── check.yml │ └── gh-pages.yml ├── typ ├── respec.typ ├── mode.typ ├── packages │ ├── vite.typ │ └── till-next.typ ├── examples │ └── justification.typ ├── templates │ ├── html-toolkit.typ │ ├── html-fix.typ │ └── template.html ├── prioritization.typ ├── icon.typ ├── util.typ └── show-example.typ ├── netlify.toml ├── .gitignore ├── tsconfig.json ├── vite.config.ts ├── index.typ ├── package.json ├── README.md ├── README.en.md └── LICENSE /scripts/typst-version.json: -------------------------------------------------------------------------------- 1 | "0.14.2" 2 | -------------------------------------------------------------------------------- /src/vite-env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | -------------------------------------------------------------------------------- /public/webapp-misspell.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/typst-doc-cn/clreq/HEAD/public/webapp-misspell.png -------------------------------------------------------------------------------- /public/font-fallback-messy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/typst-doc-cn/clreq/HEAD/public/font-fallback-messy.png -------------------------------------------------------------------------------- /public/vertical-example-modern.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/typst-doc-cn/clreq/HEAD/public/vertical-example-modern.jpg -------------------------------------------------------------------------------- /public/vertical-example-ancient.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/typst-doc-cn/clreq/HEAD/public/vertical-example-ancient.jpg -------------------------------------------------------------------------------- /.git-blame-ignore-revs: -------------------------------------------------------------------------------- 1 | # Bump formatter: tinymist 0.13.12 / typstyle 0.13.3 → tinymist 0.13.14 / typstyle 0.13.11. 2 | e6af099e5001332ca8c15abf11895b4750fc1b40 3 | # Bump formatter: … → tinymist 0.13.16 / typstyle 0.13.16. 4 | ba15e5c60dffd03df3e7cec14f80783b8e060ed0 5 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: github-actions 4 | directory: "/" 5 | schedule: 6 | interval: monthly 7 | - package-ecosystem: npm 8 | directory: "/" 9 | schedule: 10 | interval: monthly 11 | -------------------------------------------------------------------------------- /scripts/util.ts: -------------------------------------------------------------------------------- 1 | import { format as _format } from "@std/fmt/duration"; 2 | import { execFile as _execFile } from "child_process"; 3 | import { promisify } from "util"; 4 | 5 | export const duration_fmt = (ms: number) => _format(ms, { ignoreZero: true }); 6 | 7 | export const execFile = promisify(_execFile); 8 | -------------------------------------------------------------------------------- /src/main.ts: -------------------------------------------------------------------------------- 1 | import "./global.css"; 2 | 3 | // CSS styles corresponding to typst modules. 4 | import "./show-example.css"; 5 | import "./util.css"; 6 | 7 | import "./respec/mod.ts"; 8 | 9 | // For better visual effect, anchor-highlight should be loaded after respec. 10 | import "./anchor-highlight.ts"; 11 | import "./anchor-redirect.ts"; 12 | -------------------------------------------------------------------------------- /typ/respec.typ: -------------------------------------------------------------------------------- 1 | /// Loader of the table of contents (a ReSpec module) 2 | 3 | /// The table of contents that will be created by this module 4 | /// 5 | /// Usage: `#show outline: toc` 6 | #let toc = html.nav(id: "toc") 7 | 8 | /// The summary that will be created by this module 9 | /// 10 | /// Usage: `#summary` 11 | #let summary = html.ol(id: "summary") 12 | -------------------------------------------------------------------------------- /netlify.toml: -------------------------------------------------------------------------------- 1 | [build] 2 | command = "bash scripts/netlify-build.sh" 3 | 4 | 5 | [[headers]] 6 | for = "/assets/*" 7 | [headers.values] 8 | Access-Control-Allow-Origin = "*" # Allow CORS for https://services.w3.org/htmldiff 9 | 10 | 11 | [[plugins]] 12 | package = "netlify-plugin-cache" 13 | [plugins.inputs] 14 | paths = ["fonts"] 15 | 16 | [[plugins]] 17 | package = "netlify-plugin-debug-cache" 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.vscode/ 2 | 3 | /fonts/ 4 | 5 | /dist/ 6 | /public/generated/ 7 | 8 | /node_modules/ 9 | 10 | # Prefer pnpm-lock.yaml 11 | package-lock.json 12 | yarn.lock 13 | 14 | # The following lines are created by vite. 15 | 16 | # Logs 17 | logs 18 | *.log 19 | npm-debug.log* 20 | yarn-debug.log* 21 | yarn-error.log* 22 | pnpm-debug.log* 23 | lerna-debug.log* 24 | 25 | node_modules 26 | dist 27 | dist-ssr 28 | *.local 29 | 30 | # Editor directories and files 31 | .vscode/* 32 | !.vscode/extensions.json 33 | .idea 34 | .DS_Store 35 | *.suo 36 | *.ntvs* 37 | *.njsproj 38 | *.sln 39 | *.sw? 40 | -------------------------------------------------------------------------------- /src/anchor-highlight.ts: -------------------------------------------------------------------------------- 1 | import "./anchor-highlight.css"; 2 | 3 | function highlightElement(el: Element): void { 4 | const cls = "anchor-highlight"; 5 | el.classList.add(cls); 6 | 7 | el.addEventListener("animationend", () => { 8 | el.classList.remove(cls); 9 | }, { once: true }); 10 | } 11 | 12 | function highlightCurrentAnchor(): void { 13 | const id = decodeURIComponent(window.location.hash.replace(/^#/, "")); 14 | const target = document.getElementById(id); 15 | if (target !== null) { 16 | highlightElement(target); 17 | } 18 | } 19 | 20 | highlightCurrentAnchor(); 21 | window.addEventListener("hashchange", highlightCurrentAnchor); 22 | -------------------------------------------------------------------------------- /scripts/netlify-build.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -euxo pipefail 3 | 4 | TYPST_VERSION=$(jq . scripts/typst-version.json --raw-output) 5 | 6 | curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash 7 | cargo-binstall "typst-cli@$TYPST_VERSION" ripgrep 8 | # Remarks: `cargo-binstall` works, but `cargo binstall` does not. 9 | 10 | curl -OL https://www.7-zip.org/a/7z2409-linux-x64.tar.xz 11 | tar -xvf 7z2409-linux-x64.tar.xz 7zz && ln -s 7zz 7z 12 | export PATH=$PATH:$(pwd) 13 | 14 | bash scripts/download_fonts.sh 15 | 16 | pnpm install 17 | pnpm build 18 | 19 | pnpm patch-htmldiff 20 | -------------------------------------------------------------------------------- /.github/workflows/autofix.yml: -------------------------------------------------------------------------------- 1 | name: autofix.ci # needed to securely identify the workflow 2 | 3 | on: 4 | # Sync this with `./check.yml` 5 | push: 6 | branches: 7 | - main 8 | pull_request: 9 | 10 | permissions: 11 | contents: read 12 | 13 | jobs: 14 | autofix: 15 | runs-on: ubuntu-latest 16 | steps: 17 | - uses: actions/checkout@v6 18 | - uses: taiki-e/install-action@v2 19 | with: 20 | tool: fd-find,typstyle@0.13.16 # typstyle shipped with tinymist v0.13.16 21 | - name: Run typstyle 22 | run: | 23 | typstyle --inplace --line-width 120 . 24 | - uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27 25 | -------------------------------------------------------------------------------- /src/respec/mod.ts: -------------------------------------------------------------------------------- 1 | // `base.override.css` should be put _after_ `base.css`. 2 | // Reason: The former overrides the latter. 3 | import "./base.css"; 4 | import "./base.override.css"; 5 | 6 | import "./language.css"; 7 | import { createLanguageSwitch } from "./language.ts"; 8 | 9 | import "./structure.css"; 10 | import { createStructure } from "./structure.ts"; 11 | 12 | import sidebar from "./sidebar.ts"; 13 | 14 | // The order of the following matters. 15 | // Reason: 16 | // - `createStructure` creates a new `#toc` and replaces the original one, discarding all former listeners. 17 | // - `sidebar` add an event listener to `#toc` 18 | createStructure({ maxTocLevel: 2 }); 19 | sidebar(); 20 | 21 | createLanguageSwitch(); 22 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2020", 4 | "useDefineForClassFields": true, 5 | "module": "ESNext", 6 | "lib": ["ES2022", "DOM", "DOM.Iterable"], 7 | "skipLibCheck": true, 8 | 9 | /* Bundler mode */ 10 | "moduleResolution": "bundler", 11 | "allowImportingTsExtensions": true, 12 | "verbatimModuleSyntax": true, 13 | "moduleDetection": "force", 14 | "noEmit": true, 15 | 16 | /* Linting */ 17 | "strict": true, 18 | "noUnusedLocals": true, 19 | "noUnusedParameters": true, 20 | "erasableSyntaxOnly": true, 21 | "noFallthroughCasesInSwitch": true, 22 | "noUncheckedSideEffectImports": true 23 | }, 24 | "include": ["src"] 25 | } 26 | -------------------------------------------------------------------------------- /typ/mode.typ: -------------------------------------------------------------------------------- 1 | /// The mode of compilation. 2 | /// 3 | /// - pre: External cache is not ready yet, and typst code should skip these files or create alternatives. `typst query` typically sets `pre`. 4 | /// - build: External cache is ready, and typst code could use cached files. `typst compile` typically sets `build`. 5 | /// - dev: The project is running in watch mode. External cache is ready or will be ready soon, and typst code should could cached files or delegate to the vite dev server. `typst watch` typically sets `dev`. 6 | /// 7 | /// -> str 8 | #let mode = sys.inputs.at("mode", default: "build") 9 | #assert(("pre", "build", "dev").contains(mode)) 10 | 11 | #let cache-ready = ("build", "dev").contains(mode) 12 | 13 | /// Path to the external cache root. 14 | #let cache-dir = "/public/generated/" 15 | -------------------------------------------------------------------------------- /vite.config.ts: -------------------------------------------------------------------------------- 1 | import { dirname, resolve } from "node:path"; 2 | import { fileURLToPath } from "node:url"; 3 | import { defineConfig } from "vite"; 4 | import postcssNesting from "postcss-nesting"; 5 | 6 | const __dirname = dirname(fileURLToPath(import.meta.url)); 7 | 8 | export default defineConfig({ 9 | base: "./", // https://vite.dev/guide/build.html#relative-base 10 | build: { 11 | rollupOptions: { 12 | input: { 13 | main: resolve(__dirname, "src/main.ts"), 14 | theme: resolve(__dirname, "src/theme.ts"), 15 | htmldiff_nav: resolve(__dirname, "src/htmldiff-nav.ts"), 16 | }, 17 | }, 18 | manifest: true, // https://vite.dev/guide/backend-integration.html 19 | sourcemap: true 20 | }, 21 | css: { 22 | postcss: { 23 | plugins: [postcssNesting()] 24 | } 25 | } 26 | }); 27 | -------------------------------------------------------------------------------- /src/respec/base.override.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Disable justification, because it is too narrow 3 | */ 4 | :not(li) > .toc { 5 | text-align: initial; 6 | } 7 | 8 | /* Increase line-height for Chinese */ 9 | .toc { 10 | line-height: 1.5; 11 | } 12 | 13 | /* Sync color theme with ../global.css */ 14 | :root { 15 | --text: var(--main-color); 16 | --bg: var(--main-bg-color); 17 | 18 | --tocnav-normal-text: hsl(0, 0%, 44%); 19 | --tocnav-hover-bg: hsl(0, 0%, 97%); 20 | 21 | --tocsidebar-bg: #f7f8f9; 22 | --tocsidebar-heading-text: hsla(203, 20%, 40%, 0.7); 23 | } 24 | :root.dark { 25 | --tocnav-normal-text: hsl(0, 0%, 56%); 26 | --tocnav-hover-bg: hsl(0, 0%, 3%); 27 | 28 | --tocsidebar-bg: #333b4e; 29 | --tocsidebar-heading-text: hsla(203, 20%, 60%, 0.702); 30 | } 31 | /* Fix the conflict of `nav a:hover` and `.toc a:visited` */ 32 | nav.toc a:hover:visited { 33 | color: var(--main-hover-color); 34 | } 35 | -------------------------------------------------------------------------------- /src/anchor-highlight.css: -------------------------------------------------------------------------------- 1 | .anchor-highlight { 2 | animation: anchor-highlight-fade 2s ease forwards; 3 | 4 | --bg-anchor-highlight-base: rgb(250, 223, 90); 5 | :root.dark & { 6 | --bg-anchor-highlight-base: rgba(210, 188, 78, 0.95); 7 | } 8 | } 9 | 10 | /* Briefly highlight the element, then fade out. */ 11 | @keyframes anchor-highlight-fade { 12 | /* Extend box-shadow to cover the permalink (§). */ 13 | 0% { 14 | --bg: color-mix( 15 | in srgb, 16 | var(--bg-anchor-highlight-base) 95%, 17 | transparent 5% 18 | ); 19 | background-color: var(--bg); 20 | box-shadow: 0 0 0.25em 0.5em var(--bg); 21 | } 22 | 20% { 23 | --bg: color-mix( 24 | in srgb, 25 | var(--bg-anchor-highlight-base) 60%, 26 | transparent 40% 27 | ); 28 | background-color: var(--bg); 29 | box-shadow: 0 0 0.25em 0.5em var(--bg); 30 | } 31 | 100% { 32 | background-color: transparent; 33 | box-shadow: none; 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /scripts/dev.ts: -------------------------------------------------------------------------------- 1 | import fs from "node:fs/promises"; 2 | 3 | import { concurrently } from "concurrently"; 4 | 5 | import { ASSETS_SERVER_PORT, extraArgs, ROOT_DIR } from "./config.ts"; 6 | 7 | const argv = process.argv.slice(2); 8 | 9 | await fs.mkdir("dist", { recursive: true }); 10 | 11 | concurrently([ 12 | { 13 | name: "precompile", 14 | command: [ 15 | "node", 16 | "--experimental-strip-types", 17 | "scripts/precompile.ts", 18 | "--watch", 19 | ].join(" "), 20 | }, 21 | { 22 | name: "assets", 23 | command: ["vite", `--port=${ASSETS_SERVER_PORT}`].join(" "), 24 | }, 25 | { 26 | name: "main", 27 | command: [ 28 | "typst", 29 | "--color=always", 30 | "watch", 31 | "index.typ", 32 | "dist/index.html", 33 | ...extraArgs.dev, 34 | ...argv, 35 | ].join(" "), 36 | }, 37 | ], { 38 | prefix: "name", 39 | cwd: ROOT_DIR, 40 | killOthersOn: ["failure", "success"], 41 | prefixColors: "auto", 42 | }); 43 | -------------------------------------------------------------------------------- /scripts/config.ts: -------------------------------------------------------------------------------- 1 | import { dirname } from "node:path"; 2 | import { env } from "node:process"; 3 | import { fileURLToPath } from "node:url"; 4 | 5 | export const ROOT_DIR = dirname(dirname(fileURLToPath(import.meta.url))); 6 | 7 | export const envArgs = [ 8 | "--features=html", 9 | `--font-path=${ROOT_DIR}/fonts`, 10 | ]; 11 | 12 | export const ASSETS_SERVER_PORT = 5173; 13 | 14 | export const BUILD_URL_BASE = env.NETLIFY === "true" 15 | ? env.DEPLOY_URL + "/" // patch htmldiff, or assets will go to services.w3.org 16 | : (env.GITHUB_PAGES_BASE ?? "/clreq/"); 17 | 18 | /** See typ/mode.typ */ 19 | export const extraArgs = { 20 | pre: [ 21 | "--input", 22 | "mode=pre", 23 | ...envArgs, 24 | ], 25 | build: [ 26 | "--input", 27 | "mode=build", 28 | "--input", 29 | `x-url-base=${BUILD_URL_BASE}`, 30 | ...envArgs, 31 | ], 32 | dev: [ 33 | "--input", 34 | "mode=dev", 35 | "--input", 36 | `x-url-base=http://localhost:${ASSETS_SERVER_PORT}/`, 37 | ...envArgs, 38 | ], 39 | }; 40 | -------------------------------------------------------------------------------- /scripts/patch-htmldiff.template.js: -------------------------------------------------------------------------------- 1 | if ( 2 | window.location.origin + window.location.pathname === 3 | "https://services.w3.org/htmldiff" 4 | ) { 5 | // Improve readability for `
`.
 6 |   const style = document.createElement("style");
 7 |   style.textContent = `
 8 |       pre {
 9 |         white-space: normal;
10 |       }
11 |     `;
12 |   document.head.appendChild(style);
13 | 
14 |   // Replace the keyboard navigation script.
15 |   const observer = new MutationObserver((_mutations, observer) => {
16 |     const old_script = document.querySelector(
17 |       `script[src="https://w3c.github.io/htmldiff-nav/index.js"]`,
18 |     );
19 |     if (old_script !== null) {
20 |       old_script.remove();
21 |       observer.disconnect();
22 | 
23 |       const new_script = document.createElement("script");
24 |       new_script.src = "{{ HTMLDIFF-NAV-SRC }}";
25 |       new_script.type = "module";
26 |       document.head.appendChild(new_script);
27 |     }
28 |   });
29 |   observer.observe(document.head, { childList: true });
30 | }
31 | 


--------------------------------------------------------------------------------
/index.typ:
--------------------------------------------------------------------------------
 1 | #import "/typ/templates/html-toolkit.typ": load-html-template
 2 | #import "/typ/templates/html-fix.typ": html-fix
 3 | #import "/typ/respec.typ"
 4 | #import "/typ/packages/vite.typ"
 5 | 
 6 | /// Wraps the following content with the HTML template.
 7 | #show: load-html-template.with("/typ/templates/template.html", extra-head: {
 8 |   vite.load-files(("src/main.ts", "src/theme.ts#nomodule"))
 9 | })
10 | 
11 | #show: html.main
12 | 
13 | #show outline: respec.toc
14 | #show: html-fix
15 | 
16 | #show "W3C": html.abbr("W3C", title: "World Wide Web Consortium")
17 | #show figure.where(kind: table): set figure.caption(position: top)
18 | 
19 | #html.h1[
20 |   #html.span(style: "display: inline-block;")[
21 |     #link("https://www.w3.org/TR/clreq/")[clreq]-#link("https://www.w3.org/TR/clreq-gap/")[gap] for #link("https://typst.app/home")[typst]
22 |   ]
23 |   #html.span(style: "display: inline-block; font-weight: normal; font-size: 1rem; color: var(--gray-color);")[
24 |     #datetime.today().display(), typst v#sys.version
25 |   ]
26 | ]
27 | 
28 | #include "main.typ"
29 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "clreq-gap-typst",
 3 |     "version": "0.1.0",
 4 |     "private": true,
 5 |     "type": "module",
 6 |     "description": "Chinese Layout Gap Analysis for Typst",
 7 |     "dependencies": {
 8 |         "@std/fmt": "jsr:^1.0.8",
 9 |         "concurrently": "^9.2.1",
10 |         "es-toolkit": "^1.42.0",
11 |         "glob-watcher": "^6.0.0"
12 |     },
13 |     "scripts": {
14 |         "build": "tsc && node --experimental-strip-types scripts/build.ts && pnpm generate-json-index",
15 |         "dev": "node --experimental-strip-types scripts/dev.ts",
16 |         "preview": "vite preview --base=/clreq/",
17 |         "check-issues": "node --experimental-strip-types scripts/check_issues.ts",
18 |         "generate-json-index": "node --experimental-strip-types scripts/generate-json-index.ts > dist/index.json",
19 |         "patch-htmldiff": "node --experimental-strip-types scripts/patch-htmldiff.ts"
20 |     },
21 |     "devDependencies": {
22 |         "@types/glob-watcher": "^5.0.5",
23 |         "@types/node": "^24.10.1",
24 |         "postcss-nesting": "^13.0.2",
25 |         "typescript": "~5.9.3",
26 |         "vite": "^7.2.6"
27 |     },
28 |     "optionalDependencies": {
29 |         "netlify-plugin-cache": "^1.0.3"
30 |     }
31 | }


--------------------------------------------------------------------------------
/scripts/typst.ts:
--------------------------------------------------------------------------------
 1 | import assert from "node:assert";
 2 | import { spawn } from "node:child_process";
 3 | 
 4 | /** Whether to use color, passed to typst */
 5 | export type Color = "always" | "never" | "auto";
 6 | 
 7 | /**
 8 |  * Run a typst command with the given arguments.
 9 |  *
10 |  * @param args - Arguments to pass to the typst command
11 |  * @returns  - Resolves with the output of the typst command
12 |  */
13 | export function typst(
14 |   args: string[],
15 |   { stdin, color = "auto" }: { stdin?: string; color?: Color } = {},
16 | ): Promise {
17 |   return new Promise((resolve, reject) => {
18 |     const proc = spawn("typst", [`--color=${color}`, ...args]);
19 |     if (stdin) {
20 |       assert(proc.stdin !== null);
21 |       proc.stdin.write(stdin);
22 |       proc.stdin.end();
23 |     }
24 |     assert(proc.stdout !== null);
25 |     assert(proc.stderr !== null);
26 | 
27 |     const result: Buffer[] = [];
28 |     proc.stdout.on("data", (data) => {
29 |       result.push(data);
30 |     });
31 |     proc.stderr.on("data", (data) => {
32 |       process.stderr.write(data);
33 |     });
34 |     proc.on("close", (code) => {
35 |       if (code !== 0) {
36 |         reject(
37 |           new Error(
38 |             [
39 |               `Typst process exited with code ${code}`,
40 |               stdin ? ("```typst\n" + stdin + "\n```") : null,
41 |               `Args: typst ${args.join(" ")}`,
42 |             ].flatMap((x) => x).join("\n"),
43 |           ),
44 |         );
45 |       } else {
46 |         resolve(Buffer.concat(result).toString("utf-8"));
47 |       }
48 |     });
49 |   });
50 | }
51 | 


--------------------------------------------------------------------------------
/.github/workflows/pr-diff.yml:
--------------------------------------------------------------------------------
 1 | name: Comment about the difference on PR
 2 | 
 3 | on:
 4 |   pull_request_target:
 5 |     types:
 6 |       - opened
 7 | 
 8 | jobs:
 9 |   comment:
10 |     runs-on: ubuntu-latest
11 |     env:
12 |       GH_TOKEN: ${{ github.token }}
13 |     permissions:
14 |       pull-requests: write
15 |     steps:
16 |       - uses: actions/checkout@v6
17 | 
18 |       - name: Generate the comment
19 |         shell: python
20 |         run: |
21 |           from pathlib import Path
22 |           from urllib.parse import urlencode
23 | 
24 |           pr_number = "${{ github.event.pull_request.number }}"
25 | 
26 |           ref = "https://typst-doc-cn.github.io/clreq/"
27 |           pr = f"https://deploy-preview-{pr_number}--clreq-gap-typst.netlify.app/"
28 | 
29 |           base_text = "https://services.w3.org/htmldiff?"
30 |           base_pixel = "https://pianomister.github.io/diffsite/?"
31 | 
32 |           diff_text = base_text + urlencode({"doc1": ref, "doc2": pr})
33 |           diff_pixel = base_pixel + urlencode({"url1": ref, "url2": pr})
34 | 
35 |           comment = f"""
36 |           ### Diff between [#{pr_number}]({pr}) and [main]({ref})
37 | 
38 |           - [text diff]({diff_text})
39 |           - [pixel diff]({diff_pixel})
40 | 
41 |           [Feedback](https://github.com/typst-doc-cn/clreq/discussions/9)
42 |           """.strip()
43 | 
44 |           Path("comment.md").write_text(comment, encoding="utf-8")
45 | 
46 |       - name: Write the summary
47 |         run: |
48 |           cat comment.md >> "$GITHUB_STEP_SUMMARY"
49 | 
50 |       - name: Comment on the pull request
51 |         run: gh pr comment ${{ github.event.pull_request.number }} --body-file comment.md
52 |         env:
53 |           GH_TOKEN: ${{ github.token }}
54 | 


--------------------------------------------------------------------------------
/scripts/download_fonts.sh:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env bash
 2 | set -euxo pipefail
 3 | 
 4 | mkdir -p fonts
 5 | cd fonts
 6 | 
 7 | # Noto Serif CJK SC
 8 | if ! typst fonts --font-path . | rg --quiet '^Noto Serif CJK SC$'; then
 9 |   curl --location --remote-name https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/09_NotoSerifCJKsc.zip
10 |   7z x 09_NotoSerifCJKsc.zip
11 |   rm 09_NotoSerifCJKsc.zip
12 | fi
13 | 
14 | # Noto Color Emoji, the CBDT/CBLC version
15 | # See https://github.com/typst/typst/issues/6611 for reasons.
16 | if ! typst fonts --font-path . | rg --quiet '^Noto Color Emoji$'; then
17 |   curl --location --remote-name https://github.com/googlefonts/noto-emoji/raw/main/fonts/NotoColorEmoji.ttf
18 | fi
19 | 
20 | # Source Han Serif SC VF
21 | if ! typst fonts --font-path . | rg --quiet '^Source Han Serif SC VF$'; then
22 |   curl --location --remote-name https://mirrors.cernet.edu.cn/adobe-fonts/source-han-serif/Variable/OTF/SourceHanSerifSC-VF.otf
23 | fi
24 | 
25 | # A specific version of SimSun
26 | if ! typst fonts --font-path . | rg --quiet '^SimSun$'; then
27 |   curl --location --remote-name https://github.com/typst-doc-cn/guide/releases/download/files/fonts.7z
28 |   7z x fonts.7z -ofonts
29 |   rm fonts.7z
30 | fi
31 | 
32 | # MOESongUN
33 | if ! typst fonts --font-path . | rg --quiet '^MOESongUN$'; then
34 |   curl --location --remote-name https://language.moe.gov.tw/001/Upload/Files/site_content/M0001/eduSong_Unicode.zip
35 |   7z x eduSong_Unicode.zip -ofonts
36 |   rm eduSong_Unicode.zip
37 |   # The original filename in the zip has (2024年12月) encoded in Big5, resulting in garbage characters.
38 |   mv fonts/eduSong_Unicode*.ttf 'fonts/eduSong_Unicode(2024年12月).ttf'
39 | fi
40 | 
41 | # Check
42 | typst fonts --font-path . --ignore-system-fonts
43 | 
44 | cd -
45 | 


--------------------------------------------------------------------------------
/typ/packages/vite.typ:
--------------------------------------------------------------------------------
 1 | /// Integrate typst as a backend for vite
 2 | /// https://vite.dev/guide/backend-integration.html
 3 | 
 4 | #import "../templates/html-toolkit.typ": asset-url
 5 | #import "../mode.typ": mode
 6 | 
 7 | #let manifest-path = "/dist/.vite/manifest.json"
 8 | 
 9 | /// - raw-path (str):
10 | /// -> (path: str, as-module: bool)
11 | #let _parse-path(raw-path) = {
12 |   if raw-path.ends-with("#nomodule") {
13 |     (path: raw-path.trim("#nomodule", at: end), as-module: false)
14 |   } else {
15 |     (path: raw-path, as-module: true)
16 |   }
17 | }
18 | 
19 | /// Load a file
20 | ///
21 | /// All scripts will be loaded as a module be default.
22 | ///
23 | /// If a script should be executed before DOM is loaded, add a `#nomodule` suffix.
24 | /// Note that it is not officially supported by vite, and does not work in `dev` mode.
25 | ///
26 | /// - paths (array): Path to typescript entry points.
27 | /// -> content
28 | #let load-files(paths) = {
29 |   let url(path) = asset-url("/" + path)
30 | 
31 |   if mode == "dev" {
32 |     html.script(type: "module", src: url("@vite/client"))
33 |     for raw-path in paths {
34 |       let (path, as-module) = _parse-path(raw-path)
35 |       html.script(type: "module", src: url(path))
36 |     }
37 |   } else {
38 |     let manifest = json(manifest-path)
39 | 
40 |     for raw-path in paths {
41 |       let (path, as-module) = _parse-path(raw-path)
42 |       let chunk = manifest.at(path)
43 | 
44 |       assert("imports" not in chunk, message: "the `imports` field is not supported yet")
45 | 
46 |       html.script(src: url(chunk.file), ..if as-module { (type: "module") })
47 | 
48 |       for css in chunk.at("css", default: ()) {
49 |         html.link(rel: "stylesheet", href: url(css))
50 |       }
51 |     }
52 |   }
53 | }
54 | 


--------------------------------------------------------------------------------
/src/respec/language.css:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Multilingual, adapted from clreq.
 3 |  * https://github.com/w3c/clreq/blob/2526efd3a66daa35d453784f9200cb20c6cfff1d/local.css#L132-L152
 4 |  */
 5 | 
 6 | #lang-switch {
 7 |   position: fixed;
 8 |   z-index: 10000;
 9 |   top: 100px;
10 |   right: 10px;
11 | 
12 |   display: grid;
13 |   row-gap: 0.3em;
14 |   width: 4.5em;
15 | 
16 |   > * {
17 |     display: block;
18 |     padding: 2px 0.8em;
19 |     border: 1px solid var(--gray-color);
20 |     border-radius: 8px;
21 |     color: var(--main-color);
22 |     background: var(--nav-bg-color);
23 |   }
24 |   :root:not(.monolingual) & > [data-lang="zh"]::before {
25 |     content: "";
26 |     display: inline-block;
27 | 
28 |     position: relative;
29 |     width: 3px;
30 |     margin-right: -3px;
31 |     right: calc(1.5px + 0.3em);
32 | 
33 |     height: 1em;
34 |     top: 2px;
35 | 
36 |     background-color: rgba(248, 138, 5, 0.5);
37 |   }
38 | 
39 |   > :hover,
40 |   > .checked {
41 |     box-shadow: 0 2px 8px var(--gray-color);
42 |   }
43 |   > .checked {
44 |     color: var(--accent);
45 |     font-weight: bold;
46 |   }
47 |   > :active {
48 |     background: var(--accent-dark);
49 |     transition: outline 0.1s;
50 |   }
51 | }
52 | h1 {
53 |   /* left room for #lang-switch */
54 |   margin-right: 5rem;
55 | }
56 | 
57 | :root:not(.monolingual) {
58 |   /* https://github.com/w3c/clreq/blob/2526efd3a66daa35d453784f9200cb20c6cfff1d/local.css#L179-L205 */
59 |   [its-locale-filter-list="zh"] {
60 |     border-left: 3px solid rgba(248, 138, 5, 0.5);
61 |   }
62 |   span[its-locale-filter-list="zh"] {
63 |     display: inline-block;
64 |     margin-left: 0.3em;
65 |     padding-left: 0.3em;
66 |   }
67 |   p[its-locale-filter-list="zh"] {
68 |     margin-left: calc(-0.4em - 2px);
69 |     padding-left: 0.4em;
70 |   }
71 | }
72 | 


--------------------------------------------------------------------------------
/typ/examples/justification.typ:
--------------------------------------------------------------------------------
 1 | #let cell(align: center, width: 1em, body) = box(width: width, stroke: none, std.align(align, {
 2 |   // Align with texts outside any cell.
 3 |   //
 4 |   // The box’s bottom touches the baseline, which can't be changed.
 5 |   // Therefore, we have to change the bottom edge of box's content.
 6 |   set text(bottom-edge: "baseline")
 7 | 
 8 |   body
 9 | }))
10 | 
11 | #let example(page-width: 8em, page-n-rows: 5, headers: (), pages: ()) = {
12 |   assert.eq(headers.len(), pages.len())
13 | 
14 |   set text(
15 |     // It's necessary for drawing grids
16 |     top-edge: "ascender",
17 |     bottom-edge: "descender",
18 |     // We cannot mix font.
19 |     // Otherwise, numbers and Han chars will not align, because distance(bottom-edge, baseline) = distance(descender, baseline) varies with fonts.
20 |     font: "Noto Serif CJK SC",
21 |   )
22 | 
23 |   set raw(lang: "typm")
24 |   show raw: set text(0.9em)
25 | 
26 |   set box(stroke: 0.5pt)
27 | 
28 |   grid(
29 |     columns: (page-width,) * headers.len(),
30 |     column-gutter: 2em,
31 |     row-gutter: 1em,
32 |     ..headers.map(text.with(0.75em, font: "New Computer Modern")).map(grid.cell.with(align: center + horizon)),
33 |     ..pages.map(it => {
34 |       // Cells
35 |       place(top + start, {
36 |         let stroke-box = box(stroke: green, width: 1em, height: 1em)
37 |         let fill-box = box(stroke: green, fill: green.lighten(50%), width: 1em, height: 1em)
38 |         (
39 |           (
40 |             (stroke-box,) * int(page-width / 1em - 1) + (fill-box,)
41 |           )
42 |             * page-n-rows
43 |         ).join()
44 |       })
45 | 
46 |       // Frame
47 |       place(top + start, box(
48 |         stroke: (
49 |           x: purple.mix(blue).lighten(50%),
50 |           y: purple.lighten(50%),
51 |         ),
52 |         hide(it),
53 |       ))
54 | 
55 |       it
56 |       parbreak()
57 |       it
58 |     })
59 |   )
60 | }
61 | 


--------------------------------------------------------------------------------
/src/util.css:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Companion of typ/util.typ.
 3 |  */
 4 | 
 5 | /* `#prompt` */
 6 | article.prompt {
 7 |   font-size: 90%;
 8 |   color: var(--gray-color);
 9 | 
10 |   > .license {
11 |     font-size: 80%;
12 |   }
13 | }
14 | 
15 | /* Small links containing icons */
16 | .unbreakable {
17 |   display: inline-block;
18 | }
19 | 
20 | /* `#unichar` */
21 | /* Inspired by clreq `.uname` and Wikipedia [[Template:Unichar]] */
22 | .unichar {
23 |   .code-point {
24 |     font-family: monospace;
25 |     font-size: 0.8em;
26 |     letter-spacing: 0.03em;
27 |   }
28 |   .small-caps {
29 |     font-variant-caps: small-caps;
30 |   }
31 | }
32 | 
33 | /* `#note` */
34 | aside.note {
35 |   margin-block: 1em;
36 |   border-left: 3px solid var(--accent);
37 |   border-radius: 8px;
38 |   padding-inline: 1.5em;
39 |   padding-block: 0.5em;
40 | 
41 |   > .note-title {
42 |     margin-top: 0;
43 |     font-weight: bold;
44 |     color: var(--accent);
45 |   }
46 | }
47 | 
48 | /* `details.now-fixed` */
49 | details.now-fixed {
50 |   margin-block: 1em;
51 |   border-left: 3px solid var(--accent);
52 |   border-radius: 8px;
53 |   padding-inline-start: 1.5em;
54 |   padding-block: 0.5em;
55 | 
56 |   > summary {
57 |     cursor: pointer;
58 |     margin-left: -0.5em;
59 |     margin-bottom: 0.25em;
60 | 
61 |     display: grid;
62 |     grid-template-columns: auto 1fr;
63 |     align-items: center;
64 | 
65 |     font-weight: bold;
66 |     color: var(--accent);
67 | 
68 |     /* Replace ::marker with ::before */
69 |     list-style: none;
70 |     &::-webkit-details-marker {
71 |       display: none;
72 |     }
73 | 
74 |     &::before {
75 |       display: flex;
76 |       align-items: center;
77 |       height: 2em;
78 |       width: 2em;
79 |     }
80 | 
81 |     > p {
82 |       margin-block: 0;
83 |     }
84 |   }
85 | 
86 |   > summary::before {
87 |     content: "▶";
88 |   }
89 |   &[open] > summary::before {
90 |     content: "▼";
91 |   }
92 | }
93 | 


--------------------------------------------------------------------------------
/typ/packages/till-next.typ:
--------------------------------------------------------------------------------
 1 | /// Apply a function to the following content until next heading or `#till-next`.
 2 | ///
 3 | /// = Usage
 4 | ///
 5 | /// == Input
 6 | ///
 7 | /// ```
 8 | /// #show: mark-till-next
 9 | ///
10 | /// A
11 | ///
12 | /// #till-next(wrapper)
13 | ///
14 | /// B
15 | ///
16 | /// C
17 | ///
18 | /// = Heading
19 | ///
20 | /// D
21 | /// ```
22 | ///
23 | /// == Equivalent output
24 | ///
25 | /// ```
26 | /// A
27 | ///
28 | /// #wrapper[
29 | ///   B
30 | ///
31 | ///   C
32 | /// ]
33 | ///
34 | /// = Heading
35 | ///
36 | /// D
37 | /// ```
38 | ///
39 | /// = Known behaviours
40 | ///
41 | // - `#till-next` should be put at the same level of `#show: mark-till-next`, or it will be ignored.
42 | // - If you put two `#till-next` consecutively, then the former `#till-next` will receive a space `[ ]`, not `none`.
43 | #let till-next(fn) = metadata((till-next: fn))
44 | 
45 | /// A show rule that makes `#till-next(fn)` effective.
46 | ///
47 | /// Usage: `#show: mark-till-next`
48 | #let mark-till-next(body) = {
49 |   // The wrapper function
50 |   let fn = none
51 |   // The fenced elements to be wrapped
52 |   let fenced = ()
53 | 
54 |   for it in body.children {
55 |     let is-the-metadata = it.func() == metadata and it.value.keys().contains("till-next")
56 |     let is-heading = it.func() == heading
57 | 
58 |     if is-the-metadata or is-heading {
59 |       if fn != none {
60 |         // Complete the last fence
61 |         fn(fenced.join())
62 |         fn = none
63 |         fenced = ()
64 |       }
65 |       if is-the-metadata {
66 |         // Start a new fence
67 |         fn = it.value.till-next
68 |       } else {
69 |         it
70 |       }
71 |     } else if fn != none {
72 |       // Continue the fence
73 |       fenced.push(it)
74 |     } else {
75 |       it // if not in any fence
76 |     }
77 |   }
78 | 
79 |   // Complete the last fence
80 |   if fn != none {
81 |     fn(fenced.join())
82 |   }
83 | }
84 | 


--------------------------------------------------------------------------------
/scripts/patch-htmldiff.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Patch htmldiff
 3 |  *
 4 |  * https://services.w3.org/htmldiff is running `htmldiff` (the python script),
 5 |  * and it will execute `htmldiff.pl` in CLI (rather than CGI) mode.
 6 |  *
 7 |  * The commit version might be the following:
 8 |  * https://github.com/w3c/htmldiff-ui/blob/5eac9b073c66b24422df613a537da2ec2f97f457/htmldiff.pl
 9 |  *
10 |  * ## Improve readability for ``
11 |  *
12 |  * This is a bug of htmldiff.
13 |  *
14 |  * When `` and `` is on the same line, `splitit` should set `$preformatted` to true, but not.
15 |  * https://github.com/w3c/htmldiff-ui/blob/main/htmldiff.pl#L406-L412
16 |  *
17 |  * Additionally, `markit` will drop all characters after `<` for deleted (or replaced) lines.
18 |  * As a result, htmldiff does not work as expected even if `$preformatted` has been set to true`.
19 |  * https://github.com/w3c/htmldiff-ui/blob/5eac9b073c66b24422df613a537da2ec2f97f457/htmldiff.pl#L167-L168
20 |  *
21 |  * Therefore, let us ignore it…
22 |  *
23 |  * ## Replace the keyboard navigation script
24 |  *
25 |  * Replace it with src/htmldiff-nav.ts
26 |  */
27 | 
28 | import { readFile, writeFile } from "node:fs/promises";
29 | import path from "node:path";
30 | 
31 | import { BUILD_URL_BASE, ROOT_DIR } from "./config.ts";
32 | 
33 | const dist = path.join(ROOT_DIR, "dist");
34 | 
35 | const manifest = JSON.parse(
36 |   await readFile(path.join(dist, ".vite/manifest.json"), { encoding: "utf-8" }),
37 | );
38 | const htmldiff_nav = manifest["src/htmldiff-nav.ts"].file as string;
39 | 
40 | const script =
41 |   (await readFile(path.join(ROOT_DIR, "scripts/patch-htmldiff.template.js"), {
42 |     encoding: "utf-8",
43 |   }))
44 |     .replace("{{ HTMLDIFF-NAV-SRC }}", `${BUILD_URL_BASE}${htmldiff_nav}`);
45 | 
46 | const index_html = path.join(dist, "index.html");
47 | 
48 | await writeFile(
49 |   index_html,
50 |   (await readFile(index_html, { encoding: "utf-8" })).replace(
51 |     "",
52 |     ``,
53 |   ),
54 | );
55 | 


--------------------------------------------------------------------------------
/.github/workflows/cron.yml:
--------------------------------------------------------------------------------
 1 | name: Scheduled check
 2 | 
 3 | on:
 4 |   schedule:
 5 |     - cron: "0 1 28 * *"
 6 |       # At 01:00 on day-of-month 28. (UTC)
 7 |       # https://crontab.guru/#0_1_28_*_*
 8 |   workflow_dispatch:
 9 | 
10 | permissions:
11 |   issues: write
12 | 
13 | jobs:
14 |   check-issues:
15 |     runs-on: ubuntu-latest
16 |     steps:
17 |       - uses: actions/checkout@v6
18 |       - uses: pnpm/action-setup@v4
19 |         with:
20 |           version: 10
21 |       - uses: actions/setup-node@v6
22 |         with:
23 |           node-version: 22
24 |           cache: pnpm
25 |       - name: Load typst-version
26 |         run: |
27 |           echo "TYPST_VERSION=$(jq . scripts/typst-version.json --raw-output)" >> "$GITHUB_ENV"
28 |       - uses: typst-community/setup-typst@v4
29 |         with:
30 |           typst-version: v${{ env.TYPST_VERSION }}
31 |       - run: pnpm install
32 |       - name: Check issues and generate a report
33 |         id: check
34 |         continue-on-error: true
35 |         run: |
36 |           pnpm check-issues --assert-all-covered
37 |         env:
38 |           GH_TOKEN: ${{ github.token }}
39 |       - name: Find last report
40 |         uses: micalevisk/last-issue-action@v2
41 |         id: issue
42 |         with:
43 |           state: open
44 |           labels: |
45 |             cron-check
46 |       - name: Get date
47 |         id: date
48 |         shell: bash
49 |         run: |
50 |           echo "date=$(date --utc --iso-8601)" >> "$GITHUB_OUTPUT"
51 |       - name: Create or update the report
52 |         # If there is no last report and the check failed, create one.
53 |         # If there was a report, update it.
54 |         if: steps.issue.outputs.has-found == 'true' || steps.check.outcome == 'failure'
55 |         uses: peter-evans/create-issue-from-file@v6
56 |         with:
57 |           title: 🤖 Cron check (${{ steps.date.outputs.date }})
58 |           # Update an existing issue if one was found (issue-number),
59 |           # otherwise an empty value creates a new issue:
60 |           issue-number: "${{ steps.issue.outputs.issue-number }}"
61 |           content-filepath: "${{ steps.check.outputs.report-file }}"
62 |           labels: |
63 |             cron-check
64 | 


--------------------------------------------------------------------------------
/.github/workflows/check.yml:
--------------------------------------------------------------------------------
 1 | name: Check
 2 | 
 3 | on:
 4 |   # Sync this with `./autofix.yml`
 5 |   push:
 6 |     branches:
 7 |       - main
 8 |   pull_request:
 9 | 
10 | jobs:
11 |   build:
12 |     runs-on: ubuntu-latest
13 |     steps:
14 |       - uses: actions/checkout@v6
15 |       - uses: pnpm/action-setup@v4
16 |         with:
17 |           version: 10
18 |       - uses: actions/setup-node@v6
19 |         with:
20 |           node-version: 22
21 |           cache: pnpm
22 |       - name: Load typst-version
23 |         run: |
24 |           echo "TYPST_VERSION=$(jq . scripts/typst-version.json --raw-output)" >> "$GITHUB_ENV"
25 |       - uses: typst-community/setup-typst@v4
26 |         with:
27 |           typst-version: v${{ env.TYPST_VERSION }}
28 |       - name: Restore cached fonts
29 |         uses: actions/cache@v4
30 |         id: cache
31 |         with:
32 |           path: |
33 |             fonts/
34 |           key: fonts-${{ hashFiles('scripts/download_fonts.sh') }}
35 |           restore-keys: |
36 |             fonts-${{ hashFiles('scripts/download_fonts.sh') }}
37 |             fonts-
38 |       - uses: taiki-e/install-action@v2
39 |         if: steps.cache.outputs.cache-hit != 'true'
40 |         with:
41 |           tool: ripgrep
42 |       - name: Install fonts
43 |         shell: bash
44 |         if: steps.cache.outputs.cache-hit != 'true'
45 |         run: |
46 |           bash scripts/download_fonts.sh
47 |       - run: pnpm install
48 |       - run: pnpm build
49 |       - uses: actions/upload-artifact@v5
50 |         with:
51 |           name: dist
52 |           path: "./dist"
53 |   check-issues:
54 |     runs-on: ubuntu-latest
55 |     steps:
56 |       - uses: actions/checkout@v6
57 |       - uses: pnpm/action-setup@v4
58 |         with:
59 |           version: 10
60 |       - uses: actions/setup-node@v6
61 |         with:
62 |           node-version: 22
63 |           cache: pnpm
64 |       - name: Load typst-version
65 |         run: |
66 |           echo "TYPST_VERSION=$(jq . scripts/typst-version.json --raw-output)" >> "$GITHUB_ENV"
67 |       - uses: typst-community/setup-typst@v4
68 |         with:
69 |           typst-version: v${{ env.TYPST_VERSION }}
70 |       - run: pnpm install
71 |       - run: |
72 |           pnpm check-issues
73 |         env:
74 |           GH_TOKEN: ${{ github.token }}
75 | 


--------------------------------------------------------------------------------
/src/theme.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Theme toggle.
 3 |  *
 4 |  * This script should be executed before DOM is loaded.
 5 |  * Otherwise, the screen will flash in the dark mode.
 6 |  */
 7 | 
 8 | type Theme = "auto" | "light" | "dark";
 9 | 
10 | /** Same as `applyTheme`, but works before DOM is loaded */
11 | function applyThemeWithoutDOM(theme: Theme): void {
12 |   // Change the page’s theme
13 |   const resolved = theme === "auto" ? getSystemTheme() : theme;
14 |   if (resolved === "dark") {
15 |     document.documentElement.classList.add("dark");
16 |   } else {
17 |     document.documentElement.classList.remove("dark");
18 |   }
19 | }
20 | 
21 | // Load saved theme preference or default to auto (sync system)
22 | if (typeof localStorage !== "undefined") {
23 |   const theme = localStorage.getItem("theme") ?? "auto";
24 |   applyThemeWithoutDOM(theme as Theme);
25 | }
26 | 
27 | document.addEventListener("DOMContentLoaded", () => {
28 |   const themeToggle = document.getElementById("theme-toggle") as HTMLElement;
29 |   const themeSelections: HTMLDivElement[] = Array.from(
30 |     themeToggle.querySelectorAll("div.theme-icon"),
31 |   );
32 | 
33 |   // Load saved theme preference or default to auto (sync system)
34 |   if (typeof localStorage !== "undefined") {
35 |     const theme = localStorage.getItem("theme") ?? "auto";
36 |     applyTheme(theme as Theme);
37 |   }
38 | 
39 |   // Theme toggle functionality
40 |   themeToggle.addEventListener("click", () => {
41 |     const current = themeSelections.findIndex((icon) => !icon.hidden);
42 |     const next =
43 |       themeSelections[(current + 1) % themeSelections.length].classList;
44 |     const theme = next.contains("auto")
45 |       ? "auto"
46 |       : next.contains("light")
47 |       ? "light"
48 |       : "dark";
49 |     applyTheme(theme);
50 |   });
51 | 
52 |   function applyTheme(theme: Theme): void {
53 |     applyThemeWithoutDOM(theme);
54 | 
55 |     // Update theme selections
56 |     themeSelections.forEach((icon) => {
57 |       icon.hidden = !icon.classList.contains(theme);
58 |     });
59 | 
60 |     // Save for future loads
61 |     localStorage.setItem("theme", theme);
62 |   }
63 | });
64 | 
65 | function getSystemTheme(): "dark" | "light" {
66 |   const match = window.matchMedia &&
67 |     window.matchMedia("(prefers-color-scheme: dark)").matches;
68 |   return match ? "dark" : "light";
69 | }
70 | 


--------------------------------------------------------------------------------
/.github/workflows/gh-pages.yml:
--------------------------------------------------------------------------------
 1 | name: clreq::gh_pages
 2 | 
 3 | on:
 4 |   # Runs on pushes targeting the default branch
 5 |   push:
 6 |     branches: ["main"]
 7 | 
 8 |   # Allows you to run this workflow manually from the Actions tab
 9 |   workflow_dispatch:
10 | 
11 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12 | permissions:
13 |   pages: write
14 |   id-token: write
15 |   contents: read
16 | 
17 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19 | concurrency:
20 |   group: "pages"
21 |   cancel-in-progress: false
22 | 
23 | env:
24 |   GITHUB_PAGES_BASE: "/${{ github.event.repository.name }}/"
25 | 
26 | jobs:
27 |   build-gh-pages:
28 |     runs-on: ubuntu-latest
29 |     environment:
30 |       name: github-pages
31 |       url: ${{ steps.deployment.outputs.page_url }}
32 |     steps:
33 |       - uses: actions/checkout@v6
34 |       - uses: pnpm/action-setup@v4
35 |         with:
36 |           version: 10
37 |       - uses: actions/setup-node@v6
38 |         with:
39 |           node-version: 22
40 |           cache: pnpm
41 |       - name: Load typst-version
42 |         run: |
43 |           echo "TYPST_VERSION=$(jq . scripts/typst-version.json --raw-output)" >> "$GITHUB_ENV"
44 |       - uses: typst-community/setup-typst@v4
45 |         with:
46 |           typst-version: v${{ env.TYPST_VERSION }}
47 |       - name: Restore cached fonts
48 |         uses: actions/cache@v4
49 |         id: cache
50 |         with:
51 |           path: |
52 |             fonts/
53 |           key: fonts-${{ hashFiles('scripts/download_fonts.sh') }}
54 |           restore-keys: |
55 |             fonts-${{ hashFiles('scripts/download_fonts.sh') }}
56 |             fonts-
57 |       - uses: taiki-e/install-action@v2
58 |         with:
59 |           tool: ripgrep
60 |       - name: Install fonts
61 |         shell: bash
62 |         if: steps.cache.outputs.cache-hit != 'true'
63 |         run: |
64 |           bash scripts/download_fonts.sh
65 |       - run: pnpm install
66 |       - run: pnpm build
67 |       - run: pnpm patch-htmldiff
68 |       - name: Setup Pages
69 |         uses: actions/configure-pages@v5
70 |       - name: Upload artifact
71 |         uses: actions/upload-pages-artifact@v4
72 |         with:
73 |           path: "./dist"
74 |       - name: Deploy to GitHub Pages
75 |         id: deployment
76 |         uses: actions/deploy-pages@v4
77 | 


--------------------------------------------------------------------------------
/src/show-example.css:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Stylize examples created by typ/show-example.typ.
 3 |  */
 4 | 
 5 | .example {
 6 |   display: flex;
 7 |   flex-wrap: wrap;
 8 |   gap: 1em;
 9 | 
10 |   > * {
11 |     flex: auto;
12 |   }
13 | 
14 |   > pre {
15 |     overflow-x: auto;
16 |   }
17 | 
18 |   > .preview {
19 |     border-radius: 8px;
20 |     /* Copied from typst.app/docs `.preview` */
21 |     align-items: center;
22 |     background: #e4e5ea;
23 |     display: flex;
24 |     flex-direction: column;
25 |     gap: 16px;
26 |     justify-content: center;
27 |     padding: 12px 16px;
28 | 
29 |     > svg.typst-frame, img {
30 |       /* The visual padding is the sum of CSS padding and SVG inset. See `render-examples` in show-example.typ */
31 |       padding: 0.5em;
32 |       border-radius: 8px;
33 |       /* Copied from typst.app/docs `.preview > *` */
34 |       background: #fff;
35 |       box-shadow: 0 4px 12px rgba(89, 85, 101, 0.2);
36 |       height: auto;
37 |       max-height: 100%;
38 |       max-width: 100%;
39 |       width: auto;
40 |     }
41 |   }
42 | }
43 | .dark .example > .preview {
44 |   background: darkgray;
45 | 
46 |   > svg.typst-frame {
47 |     background: lightgray;
48 |   }
49 | }
50 | 
51 | /*
52 |  * Adapt the syntax highlighting palette to the dark theme
53 |  *
54 |  * In typst v0.14, `text.fill` in `raw` turn into inline `style="color: #rrggbb" attributes.
55 |  * We have to use `!important` to override them.
56 |  * https://forum.typst.app/t/how-to-support-syntax-highlighting-for-html-dark-theme-in-v0-14-0-rc-1/6380/2
57 |  */
58 | .dark main code span {
59 |   /**
60 |    * Check all possible colors by executing the following in the browser console:
61 |    *   [...new Set($$("span[style^='color:']").map((e) => e.outerHTML.match(/style="color: (#[0-9a-f]+?)"/)[1]))].sort()
62 |    * Then improve the contrast ratio:
63 |    *   https://webaim.org/resources/contrastchecker/?bcolor=212737
64 |    * (See also https://github.com/typst/typst/blob/v0.14.0-rc.1/crates/typst-library/src/text/raw.rs#L942-L972.)
65 |    */
66 |   &[style="color: #1d6c76"] {
67 |     color: #36bfce !important;
68 |   }
69 |   &[style="color: #198810"] {
70 |     color: #38be13 !important;
71 |   }
72 |   &[style="color: #4b69c6"] {
73 |     color: #92a5dd !important;
74 |   }
75 |   &[style="color: #6b6b6f"] {
76 |     color: #ababab !important;
77 |   }
78 |   &[style="color: #74747c"] {
79 |     color: #c497d8 !important;
80 |   }
81 |   &[style="color: #b60157"] {
82 |     color: #fe90c7 !important;
83 |   }
84 |   &[style="color: #d73a49"] {
85 |     color: #e5858d !important;
86 |   }
87 | }
88 | 


--------------------------------------------------------------------------------
/scripts/build.ts:
--------------------------------------------------------------------------------
 1 | import { env } from "node:process";
 2 | import { fileURLToPath } from "node:url";
 3 | import { build as vite_build } from "vite";
 4 | 
 5 | import { extraArgs } from "./config.ts";
 6 | import { precompile } from "./precompile.ts";
 7 | import { typst } from "./typst.ts";
 8 | import { duration_fmt, execFile } from "./util.ts";
 9 | 
10 | interface GitInfo {
11 |   name: string;
12 |   commit_url: string;
13 |   log_url: string;
14 |   /** latest git log */
15 |   latest_log: string;
16 | }
17 | 
18 | async function git_info(): Promise {
19 |   const git_log = execFile("git", [
20 |     "log",
21 |     "--max-count=1",
22 |     "--pretty=fuller",
23 |     "--date=iso",
24 |   ]).then(({ stdout }) => stdout.trim());
25 | 
26 |   if (env.GITHUB_ACTIONS === "true") {
27 |     // https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
28 |     const base = `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}`;
29 |     return {
30 |       name: `${env.GITHUB_SHA?.slice(0, 8)} (${env.GITHUB_REF_NAME})`,
31 |       commit_url: `${base}/commit/${env.GITHUB_SHA}`,
32 |       log_url: `${base}/actions/runs/${env.GITHUB_RUN_ID}`,
33 |       latest_log: await git_log,
34 |     };
35 |   } else if (env.NETLIFY === "true") {
36 |     // https://docs.netlify.com/configure-builds/environment-variables/
37 |     return {
38 |       name: `${env.COMMIT_REF?.slice(0, 8)} (${env.HEAD})`,
39 |       commit_url: `${env.REPOSITORY_URL}/commit/${env.COMMIT_REF}`,
40 |       log_url:
41 |         `https://app.netlify.com/sites/${env.SITE_NAME}/deploys/${env.DEPLOY_ID}`,
42 |       latest_log: await git_log,
43 |     };
44 |   } else {
45 |     return null;
46 |   }
47 | }
48 | 
49 | function as_input(info: GitInfo | null): string[] {
50 |   return info ? ["--input", `git=${JSON.stringify(info)}`] : [];
51 | }
52 | 
53 | if (process.argv[1] === fileURLToPath(import.meta.url)) {
54 |   // These steps should be executed sequentially.
55 |   // 1. `precompile` writes `/public/generated/` processed by `vite_build`.
56 |   // 2. `vite_build` writes `/dist/.vite/manifest.json` depended by `index.typ`.
57 | 
58 |   await precompile();
59 | 
60 |   await vite_build();
61 | 
62 |   const timeStart = Date.now();
63 |   await typst([
64 |     "compile",
65 |     "index.typ",
66 |     "dist/index.html",
67 |     ...as_input(await git_info()),
68 |     ...extraArgs.build,
69 |   ]);
70 |   console.log(
71 |     `🏛️ Built the document successfully in`,
72 |     `${duration_fmt(Date.now() - timeStart)}.`,
73 |   );
74 | }
75 | 


--------------------------------------------------------------------------------
/src/respec/structure.css:
--------------------------------------------------------------------------------
  1 | /* Permalink, ./structure.js */
  2 | /* https://github.com/speced/respec/blob/eaa1596ef5c4207ab350808c1593d3a39600fbed/src/styles/respec.css.js#L148-L169 */
  3 | a.permalink {
  4 |   margin-left: -0.5em;
  5 |   width: 1em;
  6 | 
  7 |   &:not(:hover) {
  8 |     text-decoration: none;
  9 |     color: var(--gray-color);
 10 |     opacity: 0.5;
 11 |   }
 12 |   &::before {
 13 |     content: "§";
 14 |   }
 15 | }
 16 | 
 17 | /* Summary */
 18 | ol#summary {
 19 |   /* Numbers are inlined into source */
 20 |   list-style-type: none;
 21 |   padding-left: 0;
 22 | 
 23 |   display: grid;
 24 |   grid-template-columns: repeat(auto-fit, minmax(15em, 1fr));
 25 |   row-gap: 1em;
 26 | 
 27 |   > li > a {
 28 |     height: 100%;
 29 |     display: flex;
 30 |     flex-direction: column;
 31 | 
 32 |     padding-left: 1em;
 33 |     padding-right: 0.5em;
 34 | 
 35 |     color: var(--toclink-text);
 36 | 
 37 |     /* Switch to using border-bottom */
 38 |     text-decoration: none;
 39 |     border-bottom: 3px solid transparent;
 40 |     margin-bottom: -2px;
 41 | 
 42 |     &:hover {
 43 |       background: var(--a-hover-bg);
 44 |       border-bottom-color: var(--toclink-underline);
 45 |     }
 46 | 
 47 |     /* heading + v(1fr) + dots + report */
 48 |     > * {
 49 |       margin-top: 0;
 50 |       margin-bottom: 0;
 51 |     }
 52 |     > .dots {
 53 |       margin-top: auto;
 54 |     }
 55 | 
 56 |     > :first-child {
 57 |       text-indent: 0.8em hanging;
 58 |       margin-left: -1em;
 59 | 
 60 |       > .secno {
 61 |         display: inline-block;
 62 |         width: 0.8em;
 63 |       }
 64 |     }
 65 | 
 66 |     > .dots {
 67 |       margin-left: -0.25em;
 68 | 
 69 |       display: flex;
 70 |       flex-wrap: wrap-reverse;
 71 | 
 72 |       > * {
 73 |         border-radius: 50%;
 74 |         display: inline-block;
 75 | 
 76 |         border-width: 2px;
 77 |         width: calc(0.8em - 2px * 2);
 78 |         height: calc(0.8em - 2px * 2);
 79 |         margin: 0.25em;
 80 |         vertical-align: -15%;
 81 | 
 82 |         border-style: solid;
 83 |         border-color: transparent;
 84 |       }
 85 |     }
 86 | 
 87 |     :root:not(.dark) &:hover > .dots > * {
 88 |       /* Make sure tbd-level dots are visible */
 89 |       border-color: var(--main-bg-color);
 90 |       width: calc(0.8em - 2px);
 91 |       height: calc(0.8em - 2px);
 92 |       margin: calc(0.25em - 1px);
 93 |       vertical-align: -16%;
 94 |     }
 95 | 
 96 |     > .report {
 97 |       font-size: small;
 98 |       color: var(--gray-color);
 99 |     }
100 |   }
101 | }
102 | 


--------------------------------------------------------------------------------
/typ/templates/html-toolkit.typ:
--------------------------------------------------------------------------------
 1 | /// = HTML Toolkit
 2 | ///
 3 | /// This package provides a set of utility functions for working with HTML export.
 4 | 
 5 | /// CLI sets the `x-url-base` to the base URL for assets. This is needed if you host the website on the github pages.
 6 | ///
 7 | /// For example, if you host the website on `https://username.github.io/project/`, you should set `x-url-base` to `/project/`.
 8 | #let assets-url-base = sys.inputs.at("x-url-base", default: none)
 9 | /// The base URL for content.
10 | #let url-base = if assets-url-base != none { assets-url-base } else { "/dist/" }
11 | /// The base URL for assets.
12 | #let assets-url-base = if assets-url-base != none { assets-url-base } else { "/" }
13 | 
14 | /// Converts the path to the asset to the URL.
15 | ///
16 | /// - path (str): The path to the asset.
17 | /// -> str
18 | #let asset-url(path) = {
19 |   if path != none and path.starts-with("/") {
20 |     assets-url-base + path.slice(1)
21 |   } else {
22 |     path
23 |   }
24 | }
25 | 
26 | /// Converts the xml loaded data to HTML.
27 | ///
28 | /// - data (dict): The data to convert to HTML.
29 | /// -> content
30 | #let to-html(data, slot: none) = {
31 |   let to-html = to-html.with(slot: slot)
32 |   if type(data) == str {
33 |     let data = data.trim()
34 |     if data.len() > 0 {
35 |       data
36 |     }
37 |   } else {
38 |     if data.tag == "slot" {
39 |       return slot
40 |     }
41 |     if data.tag.len() == 0 {
42 |       return none
43 |     }
44 | 
45 |     let rewrite(data, attr) = {
46 |       let value = data.attrs.at(attr, default: none)
47 |       if value != none and value.starts-with("/") {
48 |         data.attrs.at(attr) = asset-url(value)
49 |       }
50 | 
51 |       data
52 |     }
53 | 
54 |     data = rewrite(data, "href")
55 |     data = rewrite(data, "src")
56 | 
57 |     html.elem(data.tag, attrs: data.attrs, data.children.map(to-html).join())
58 |   }
59 | }
60 | 
61 | /// Loads the HTML template and inserts the content.
62 | ///
63 | /// - template-path (str): The absolute path to the HTML template.
64 | /// - content (content): The body to insert into the template.
65 | /// - extra-head (content): Additional content to insert into the head.
66 | /// ->
67 | #let load-html-template(template-path, body, extra-head: none) = {
68 |   let html-elem = xml(template-path).at(0)
69 |   let html-children = html-elem.children.filter(it => type(it) != str)
70 |   let head = to-html(html-children.at(0)).body
71 |   let body = to-html(html-children.at(1), slot: body)
72 | 
73 |   html.html(..html-elem.attrs, {
74 |     html.head({
75 |       head
76 |       extra-head
77 |     })
78 |     body
79 |   })
80 | }
81 | 
82 | /// Creates an embeded block typst frame.
83 | #let div-frame(content, ..attrs) = html.div(html.frame(content), ..attrs)
84 | 


--------------------------------------------------------------------------------
/src/respec/language.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Creates and handles the language switch.
  3 |  *
  4 |  * Adapted from W3C clreq.
  5 |  *
  6 |  * https://github.com/w3c/clreq/blob/2526efd3a66daa35d453784f9200cb20c6cfff1d/index.html#L76-L81
  7 |  * https://github.com/w3c/clreq/blob/2526efd3a66daa35d453784f9200cb20c6cfff1d/src/script.ts
  8 |  * https://www.w3.org/Consortium/Legal/copyright-software
  9 |  */
 10 | 
 11 | import { html } from "./utils.ts";
 12 | 
 13 | type Language = "zh" | "en" | "all";
 14 | 
 15 | const $root = document.documentElement;
 16 | const $title = $root.querySelector("main > h1") as HTMLHeadingElement;
 17 | 
 18 | function setRoot(lang: Language): void {
 19 |   $root.lang = lang === "all" ? "zh-CN" : lang;
 20 | 
 21 |   // Update styles
 22 |   if (lang === "all") {
 23 |     $root.classList.remove("monolingual");
 24 |   } else {
 25 |     $root.classList.add("monolingual");
 26 |   }
 27 | }
 28 | 
 29 | function filterElements(lang: Language): void {
 30 |   /**
 31 |    * Multilingual elements created with `#babel` and `#bbl` in typst,
 32 |    * or dynamically created by other scripts.
 33 |    */
 34 |   const babelElements = Array.from(
 35 |     $root.querySelectorAll("[its-locale-filter-list]"),
 36 |   );
 37 | 
 38 |   for (const el of babelElements) {
 39 |     const match = lang === "all" ||
 40 |       el.getAttribute("its-locale-filter-list") === lang;
 41 |     el.hidden = !match;
 42 |   }
 43 | }
 44 | 
 45 | function applyLanguage(lang: Language, menu: HTMLElement): void {
 46 |   setRoot(lang);
 47 |   filterElements(lang);
 48 | 
 49 |   // Update selection
 50 |   Array.from(menu.children).forEach((o) => {
 51 |     // @ts-ignore
 52 |     if (o.dataset.lang === lang) {
 53 |       o.classList.add("checked");
 54 |       o.ariaChecked = "true";
 55 |     } else {
 56 |       o.classList.remove("checked");
 57 |       o.ariaChecked = "false";
 58 |     }
 59 |   });
 60 | 
 61 |   // Save for future loads
 62 |   localStorage.setItem("lang", lang);
 63 | }
 64 | 
 65 | export function createLanguageSwitch(): void {
 66 |   const menu = html`
 67 |     
 68 |       
 69 |       
 70 |       
 71 |     
 72 |   ` as HTMLElement;
 73 |   menu.addEventListener("click", (e) => {
 74 |     // @ts-ignore
 75 |     const option = e.target.closest("[data-lang]") as HTMLElement;
 76 |     if (option) {
 77 |       const lang = option.dataset.lang as Language;
 78 |       applyLanguage(lang, menu);
 79 |     }
 80 |   });
 81 | 
 82 |   applyLanguage(
 83 |     (localStorage.getItem("lang") as Language | null) ?? getSystemLanguage(),
 84 |     menu,
 85 |   );
 86 | 
 87 |   // Make the menu easily accessible by pressing tab key.
 88 |   $title.insertAdjacentElement("afterend", menu);
 89 | }
 90 | 
 91 | function getSystemLanguage(): Language {
 92 |   const languages = navigator.languages ?? [navigator.language];
 93 | 
 94 |   for (const langFull of languages) {
 95 |     const lang = langFull.split("-")[0].toLowerCase();
 96 | 
 97 |     if (lang === "zh") return "zh";
 98 |     if (lang === "en") return "en";
 99 |   }
100 |   return "all";
101 | }
102 | 


--------------------------------------------------------------------------------
/src/respec/utils.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * As the name implies, this contains a ragtag gang of methods that just don't fit anywhere else.
  3 |  *
  4 |  * Adapted from ReSpec.
  5 |  *
  6 |  * https://github.com/speced/respec/blob/eaa1596ef5c4207ab350808c1593d3a39600fbed/src/core/utils.js
  7 |  * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document
  8 |  *
  9 |  * @module
 10 |  */
 11 | 
 12 | /**
 13 |  * A simple html template tag replacement for hyperHTML
 14 |  *
 15 |  * @param strings - Template string array.
 16 |  * @param values - Values to interpolate into the template.
 17 |  * @returns - The resulting DOM element or fragment.
 18 |  */
 19 | export function html(
 20 |   strings: TemplateStringsArray,
 21 |   ...values: (string | Element | DocumentFragment)[]
 22 | ): Element | DocumentFragment {
 23 |   let str = "";
 24 |   for (let i = 0; i < strings.length; i++) {
 25 |     str += strings[i];
 26 |     if (i < values.length) {
 27 |       const value = values[i];
 28 |       if (value instanceof Element || value instanceof DocumentFragment) {
 29 |         // @ts-ignore
 30 |         str += value.outerHTML;
 31 |       } else {
 32 |         str += value;
 33 |       }
 34 |     }
 35 |   }
 36 |   const template = document.createElement("template");
 37 |   template.innerHTML = str.trim();
 38 |   return template.content.children.length === 1
 39 |     // @ts-ignore
 40 |     ? template.content.firstElementChild
 41 |     : template.content;
 42 | }
 43 | 
 44 | /**
 45 |  * Creates and sets an ID to an element (elem) using a specific prefix if
 46 |  * provided, and a specific text if given.
 47 |  * @param elem element
 48 |  * @param pfx prefix
 49 |  * @param txt text
 50 |  * @param noLC do not convert to lowercase
 51 |  * @returns generated (or existing) id for element
 52 |  */
 53 | export function addId(
 54 |   elem: HTMLElement,
 55 |   pfx: string | null = "",
 56 |   txt = "",
 57 |   noLC = false,
 58 | ): string {
 59 |   if (elem.id) {
 60 |     return elem.id;
 61 |   }
 62 |   if (!txt) {
 63 |     // @ts-ignore
 64 |     txt = (elem.title ? elem.title : elem.textContent).trim();
 65 |   }
 66 |   let id = noLC ? txt : txt.toLowerCase();
 67 |   id = id
 68 |     .trim()
 69 |     .normalize("NFD")
 70 |     .replace(/[\u0300-\u036f]/g, "")
 71 |     .replace(/\W+/gim, "-")
 72 |     .replace(/^-+/, "")
 73 |     .replace(/-+$/, "");
 74 | 
 75 |   if (!id) {
 76 |     id = "generatedID";
 77 |   } else if (/\.$/.test(id) || !/^[a-z]/i.test(pfx || id)) {
 78 |     id = `x${id}`; // trailing . doesn't play well with jQuery
 79 |   }
 80 |   if (pfx) {
 81 |     id = `${pfx}-${id}`;
 82 |   }
 83 |   if (elem.ownerDocument.getElementById(id)) {
 84 |     let i = 0;
 85 |     let nextId = `${id}-${i}`;
 86 |     while (elem.ownerDocument.getElementById(nextId)) {
 87 |       i += 1;
 88 |       nextId = `${id}-${i}`;
 89 |     }
 90 |     id = nextId;
 91 |   }
 92 |   elem.id = id;
 93 |   return id;
 94 | }
 95 | 
 96 | /**
 97 |  * Changes name of a DOM Element
 98 |  * @param elem element to rename
 99 |  * @param newName new element name
100 |  *
101 |  * @returns new renamed element
102 |  */
103 | export function renameElement(
104 |   elem: Element,
105 |   newName: string,
106 |   options = { copyAttributes: true },
107 | ): Element {
108 |   if (elem.localName === newName) return elem;
109 |   const newElement = elem.ownerDocument.createElement(newName);
110 |   // copy attributes
111 |   if (options.copyAttributes) {
112 |     for (const { name, value } of elem.attributes) {
113 |       newElement.setAttribute(name, value);
114 |     }
115 |   }
116 |   // copy child nodes
117 |   newElement.append(...elem.childNodes);
118 |   elem.replaceWith(newElement);
119 |   return newElement;
120 | }
121 | 


--------------------------------------------------------------------------------
/typ/prioritization.typ:
--------------------------------------------------------------------------------
  1 | /// Utilities on prioritization.
  2 | ///
  3 | /// Usage: Put `#level.ok`, etc. after a heading.
  4 | 
  5 | #import "templates/html-toolkit.typ": to-html
  6 | #import "mode.typ": cache-dir, cache-ready
  7 | 
  8 | /// Configuration of levels, copied from clreq-gap.
  9 | #let config = (
 10 |   ok: (paint: rgb("008000"), human: "OK"),
 11 |   advanced: (paint: rgb("ffe4b5"), human: "Advanced"),
 12 |   basic: (paint: rgb("ffa500"), human: "Basic"),
 13 |   broken: (paint: rgb("ff0000"), human: "Broken"),
 14 |   tbd: (paint: rgb("eeeeee"), human: "To be done"),
 15 |   na: (paint: rgb("008000"), human: "Not applicable"),
 16 | )
 17 | 
 18 | /// The table explaining priority levels.
 19 | ///
 20 | /// If cache is ready, use the cached `prioritization.level-table.svg`.
 21 | /// Otherwise, draw the table.
 22 | #let level-table(lang: "en") = if cache-ready {
 23 |   to-html(xml(cache-dir + "prioritization.level-table." + lang + ".svg").first())
 24 | } else {
 25 |   // When preparing other caches for the html target, skip this.
 26 |   show: it => context if target() == "paged" { it }
 27 | 
 28 |   let level = config
 29 |     .pairs()
 30 |     .map(((k, v)) => (
 31 |       k,
 32 |       grid(
 33 |         columns: 2,
 34 |         gutter: 0.5em,
 35 |         circle(radius: 0.5em, stroke: none, fill: v.paint), v.human,
 36 |       ),
 37 |     ))
 38 |     .to-dict()
 39 | 
 40 |   set text(font: ("Libertinus Serif", "Source Han Serif SC", "Noto Color Emoji"))
 41 | 
 42 |   let bbl(en, zh) = if lang == "en" { en } else { zh }
 43 | 
 44 |   table(
 45 |     columns: 3,
 46 |     align: (x, y) => (if x == 0 { end } else if y <= 1 { center } else { start }) + horizon,
 47 |     stroke: none,
 48 |     table.cell(rowspan: 2, smallcaps[*#bbl[Difficulty to Resolve][解决难度]*]),
 49 |     table.vline(),
 50 |     table.cell(colspan: 2, smallcaps[*#bbl[Issue][问题]*]),
 51 |     table.hline(stroke: 0.5pt),
 52 |     [🚲 *#bbl[Typical][常见]*],
 53 |     [🚀 *#bbl[Specialized][专业]*],
 54 |     table.hline(),
 55 |     [*#bbl[Works by default][默认即可使用]* 😃], level.ok, level.ok,
 56 |     [*#bbl[Requires simple config][只需简单设置]* ✅], level.advanced, level.ok,
 57 |     [*#bbl[Easy but not obvious][容易但不直接]* 🤨], level.basic, level.advanced,
 58 |     [*#bbl[Hard or fragile][困难而不可靠]* 💀], level.broken, level.basic,
 59 |     table.hline(stroke: 0.5pt),
 60 |     ..(
 61 |       ([*#bbl[Needs further research][等待继续调查]* 🔎], level.tbd),
 62 |       ([*#bbl[Irrelevant to this script][不涉及此文字]* 🖖], level.na),
 63 |     )
 64 |       .map(((k, v)) => (k, table.cell(colspan: 2, box(inset: (left: 27%), width: 100%, v))))
 65 |       .flatten(),
 66 |   )
 67 | }
 68 | 
 69 | #let paint-level(level) = {
 70 |   let l = config.at(level)
 71 |   // In typst v0.14, `html.span` does not support `data-*` attributes, so we have to use `html.elem("span", …)`.
 72 |   // https://github.com/typst/typst/issues/6870
 73 |   html.elem(
 74 |     "span",
 75 |     {
 76 |       html.span(
 77 |         style: "display: inline-block; width: 1em; height: 1em; margin-inline: 0.25em; vertical-align: -5%",
 78 |         box(
 79 |           html.frame(circle(radius: 0.5em * 11 / 12, stroke: none, fill: l.paint)),
 80 |         ),
 81 |       )
 82 |       l.human
 83 |     },
 84 |     attrs: (
 85 |       class: "unbreakable",
 86 |       data-priority-level: level,
 87 |     ),
 88 |   )
 89 |   [#metadata(level)]
 90 | }
 91 | 
 92 | /// Priority levels
 93 | #let level = (
 94 |   // Do not use `map` here, or LSP’s completion will be broken.
 95 |   ok: paint-level("ok"),
 96 |   advanced: paint-level("advanced"),
 97 |   basic: paint-level("basic"),
 98 |   broken: paint-level("broken"),
 99 |   tbd: paint-level("tbd"),
100 |   na: paint-level("na"),
101 | )
102 | #assert.eq(level.len(), config.len())
103 | 


--------------------------------------------------------------------------------
/typ/icon.typ:
--------------------------------------------------------------------------------
 1 | /// A wrapper for SVG to avoid `html.frame` and support dark theme.
 2 | #let _wrapper(paths) = html.span(class: "icon", html.elem(
 3 |   "svg",
 4 |   attrs: (viewBox: "0 0 16 16", width: "16", height: "16"),
 5 |   paths,
 6 | ))
 7 | 
 8 | /// https://primer.style/octicons/icon/issue-opened-16/
 9 | #let issue-open = _wrapper({
10 |   html.elem("path", attrs: (d: "M8 9.5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3Z"))
11 |   html.elem("path", attrs: (d: "M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Z"))
12 | })
13 | 
14 | /// https://primer.style/octicons/icon/issue-closed-16/
15 | #let issue-closed = _wrapper({
16 |   html.elem("path", attrs: (
17 |     d: "M11.28 6.78a.75.75 0 0 0-1.06-1.06L7.25 8.69 5.78 7.22a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.06 0l3.5-3.5Z",
18 |   ))
19 |   html.elem("path", attrs: (d: "M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0Zm-1.5 0a6.5 6.5 0 1 0-13 0 6.5 6.5 0 0 0 13 0Z"))
20 | })
21 | 
22 | /// https://primer.style/octicons/icon/git-pull-request-16/
23 | #let git-pull-request = _wrapper({
24 |   html.elem(
25 |     "path",
26 |     attrs: (
27 |       d: "M1.5 3.25a2.25 2.25 0 1 1 3 2.122v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.25 2.25 0 0 1 1.5 3.25Zm5.677-.177L9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM3.75 2.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm0 9.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm8.25.75a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Z",
28 |     ),
29 |   )
30 | })
31 | 
32 | /// https://primer.style/octicons/icon/git-pull-request-closed-16/
33 | #let git-pull-request-closed = _wrapper({
34 |   html.elem(
35 |     "path",
36 |     attrs: (
37 |       d: "M3.25 1A2.25 2.25 0 0 1 4 5.372v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.251 2.251 0 0 1 3.25 1Zm9.5 5.5a.75.75 0 0 1 .75.75v3.378a2.251 2.251 0 1 1-1.5 0V7.25a.75.75 0 0 1 .75-.75Zm-2.03-5.273a.75.75 0 0 1 1.06 0l.97.97.97-.97a.748.748 0 0 1 1.265.332.75.75 0 0 1-.205.729l-.97.97.97.97a.751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018l-.97-.97-.97.97a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734l.97-.97-.97-.97a.75.75 0 0 1 0-1.06ZM2.5 3.25a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0ZM3.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm9.5 0a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z",
38 |     ),
39 |   )
40 | })
41 | 
42 | /// https://primer.style/octicons/icon/git-merge-16/
43 | #let git-merge = _wrapper({
44 |   html.elem(
45 |     "path",
46 |     attrs: (
47 |       d: "M5.45 5.154A4.25 4.25 0 0 0 9.25 7.5h1.378a2.251 2.251 0 1 1 0 1.5H9.25A5.734 5.734 0 0 1 5 7.123v3.505a2.25 2.25 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.95-.218ZM4.25 13.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm8.5-4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5ZM5 3.25a.75.75 0 1 0 0 .005V3.25Z",
48 |     ),
49 |   )
50 | })
51 | 
52 | /// https://primer.style/octicons/icon/light-bulb-16/
53 | #let light-bulb = _wrapper(
54 |   html.elem(
55 |     "path",
56 |     attrs: (
57 |       d: "M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z",
58 |     ),
59 |   ),
60 | )
61 | 
62 | /// https://primer.style/octicons/icon/comment-16/
63 | #let comment = _wrapper(
64 |   html.elem(
65 |     "path",
66 |     attrs: (
67 |       d: "M1 2.75C1 1.784 1.784 1 2.75 1h10.5c.966 0 1.75.784 1.75 1.75v7.5A1.75 1.75 0 0 1 13.25 12H9.06l-2.573 2.573A1.458 1.458 0 0 1 4 13.543V12H2.75A1.75 1.75 0 0 1 1 10.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h4.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z",
68 |     ),
69 |   ),
70 | )
71 | 


--------------------------------------------------------------------------------
/typ/templates/html-fix.typ:
--------------------------------------------------------------------------------
  1 | /// A module providing workarounds for HTML features not supported by typst yet
  2 | 
  3 | #import "./html-toolkit.typ": asset-url
  4 | 
  5 | /// Display the linked URL in a new tab
  6 | ///
  7 | /// Usage: `#show link: link-in-new-tab`
  8 | #let link-in-new-tab(class: none, it) = html.a(
  9 |   target: "_blank",
 10 |   href: it.dest,
 11 |   ..if class != none { (class: class) },
 12 |   it.body,
 13 | )
 14 | 
 15 | /// Use proportional-width apostrophes
 16 | ///
 17 | /// The main font is for Chinese, so it uses full-width apostrophes by default.
 18 | /// For Latin texts, it is better to use proportional-width ones.
 19 | /// https://typst-doc-cn.github.io/guide/FAQ/smartquote-font.html#若中西统一使用相同字体
 20 | ///
 21 | /// Usage: `#show: enable-proportional-width`
 22 | #let latin-apostrophe = html.span.with(style: "font-feature-settings: 'pwid';")
 23 | 
 24 | /// Externalize images in /public/
 25 | ///
 26 | /// Usage: `#show image: external-image`
 27 | #let external-image(it) = {
 28 |   if type(it.source) == str and it.source.starts-with("/public/") {
 29 |     // Do not enable lazy loading here. Lazy images without explicit sizes will cause the page to flush, making links with hash anchors being unable to locate accurately.
 30 |     html.img(
 31 |       src: asset-url(it.source.trim("/public", at: start)),
 32 |       ..if it.alt != none { (alt: it.alt, title: it.alt) },
 33 |       ..if type(it.width) == relative { (style: "width:" + repr(it.width.ratio)) },
 34 |     )
 35 |   } else {
 36 |     it
 37 |   }
 38 | }
 39 | 
 40 | /// Parse a string into a length
 41 | /// Example: `"58.828pt"` → `58.828pt`
 42 | #let _pt(raw) = float(raw.trim("pt", at: end)) * 1pt
 43 | 
 44 | /// Externalize SVGs in /public/
 45 | /// Only SVGs generated by typst are tested.
 46 | ///
 47 | /// Usage: `#show image: external-svg`
 48 | #let external-svg(it) = {
 49 |   if type(it.source) == str and it.source.starts-with("/public/") and it.source.ends-with(".svg") {
 50 |     let (width, height) = xml(it.source).first().attrs
 51 |     html.img(
 52 |       src: asset-url(it.source.trim("/public", at: start)),
 53 |       loading: "lazy",
 54 |       // Copy the behaviour of `html.frame`.
 55 |       // https://github.com/typst/typst/blob/6312c6636064466556fe79bb0bf5479977fafc9b/crates/typst-svg/src/lib.rs#L70-L77
 56 |       style: "overflow: visible; width: {width}em; height: {height}em;"
 57 |         .replace("{width}", str(_pt(width) / text.size))
 58 |         .replace("{height}", str(_pt(height) / text.size)),
 59 |     )
 60 |   } else {
 61 |     it
 62 |   }
 63 | }
 64 | 
 65 | /// Improve references to headings
 66 | ///
 67 | /// Our headings are bilingual and the numbers need special formatting.
 68 | /// Therefore, we have to override the default implementation.
 69 | ///
 70 | /// Also, we want labeled headings to have anchors for permalinks.
 71 | /// https://github.com/typst/typst/issues/7381
 72 | ///
 73 | /// Usage: `#show: improve-heading-refs`
 74 | #let improve-heading-refs(body) = {
 75 |   show heading: it => {
 76 |     let has-label = it.at("label", default: none) != none
 77 |     let tag = "h" + str(it.level + 1)
 78 | 
 79 |     if it.numbering == none {
 80 |       if has-label {
 81 |         // Add id to headings in html if there exists a label
 82 |         html.elem(tag, attrs: (id: str(it.label)), it.body)
 83 |       } else {
 84 |         it
 85 |       }
 86 |     } else {
 87 |       html.elem(
 88 |         tag,
 89 |         // Add id to headings in html if there exists a label
 90 |         attrs: if has-label { (id: str(it.label)) } else { (:) },
 91 |         {
 92 |           // Wrap the numbering with a class
 93 |           html.span(counter(heading).display(it.numbering), class: "secno")
 94 |           [ ]
 95 |           it.body
 96 |         },
 97 |       )
 98 |     }
 99 |   }
100 |   // https://github.com/Glomzzz/typsite/blob/c5f99270eff92cfdad58bbf4a78ea127d1aed310/resources/root/lib.typ#L155-L167
101 |   show ref: it => {
102 |     let el = it.element
103 |     if el != none and el.func() == heading {
104 |       // Override heading references.
105 |       link(
106 |         el.location(),
107 |         // `§` is agnostic to the language.
108 |         // There should be no space between `§` and the numbers, so we cannot set `heading.supplement`.
109 |         numbering("§" + el.numbering, ..counter(heading).at(el.location())),
110 |       )
111 |     } else {
112 |       // Other references as usual.
113 |       it
114 |     }
115 |   }
116 |   body
117 | }
118 | 
119 | /// A collection of all fixes
120 | #let html-fix(body) = {
121 |   show: improve-heading-refs
122 |   show image: external-image
123 |   body
124 | }
125 | 


--------------------------------------------------------------------------------
/scripts/precompile.ts:
--------------------------------------------------------------------------------
  1 | import fs from "node:fs/promises";
  2 | import { fileURLToPath } from "node:url";
  3 | 
  4 | import watch from "glob-watcher";
  5 | 
  6 | import { envArgs, extraArgs, ROOT_DIR } from "./config.ts";
  7 | import { type Color, typst } from "./typst.ts";
  8 | import { duration_fmt } from "./util.ts";
  9 | 
 10 | const CACHE_DIR = `${ROOT_DIR}/public/generated`;
 11 | 
 12 | /**
 13 |  * The main entrypoint of precompilation.
 14 |  */
 15 | export async function precompile({ color }: { color?: Color } = {}) {
 16 |   await fs.mkdir(CACHE_DIR, { recursive: true });
 17 |   await Promise.all([
 18 |     renderExamples({ color }),
 19 |     renderPrioritization({ lang: "en", color }),
 20 |     renderPrioritization({ lang: "zh", color }),
 21 |   ]);
 22 | }
 23 | 
 24 | /**
 25 |  * Render examples from the main.typ file and compile them into SVG files.
 26 |  */
 27 | async function renderExamples({ color }: { color?: Color }) {
 28 |   type Example = { id: string; content: string };
 29 | 
 30 |   const timeStart = Date.now();
 31 | 
 32 |   const examples = JSON.parse(
 33 |     await typst([
 34 |       "query",
 35 |       "main.typ",
 36 |       "",
 37 |       "--field=value",
 38 |       "--diagnostic-format=short",
 39 |       "--target=html",
 40 |       ...extraArgs.pre,
 41 |     ], { color: color }),
 42 |   ) as Example[];
 43 |   const timeQueryEnd = Date.now();
 44 | 
 45 |   /** @returns cache-hit */
 46 |   const compileExample = async ({ id, content }: Example): Promise => {
 47 |     const output = `${CACHE_DIR}/${id}.svg`;
 48 |     const compiled = await fs.stat(output).then(() => true).catch(() => false);
 49 |     if (!compiled) {
 50 |       await typst(["compile", "-", output, ...envArgs], {
 51 |         stdin: content,
 52 |         color: color,
 53 |       });
 54 |     }
 55 |     return compiled;
 56 |   };
 57 | 
 58 |   const hit = await Promise.all(examples.map(compileExample));
 59 |   const timeCompileEnd = Date.now();
 60 | 
 61 |   const total = hit.length;
 62 |   const cached = hit.filter((h) => h).length;
 63 |   console.log(
 64 |     `\n✅ Rendered ${total} examples`,
 65 |     `(${cached} cached, ${total - cached} new)`,
 66 |     `successfully in ${duration_fmt(timeCompileEnd - timeStart)}`,
 67 |     `(query ${duration_fmt(timeQueryEnd - timeStart)},`,
 68 |     `compile ${duration_fmt(timeCompileEnd - timeQueryEnd)}).`,
 69 |   );
 70 | }
 71 | 
 72 | /**
 73 |  * Render prioritization.level-table into an SVG.
 74 |  */
 75 | async function renderPrioritization(
 76 |   { lang, color }: { lang: "en" | "zh"; color?: Color },
 77 | ): Promise {
 78 |   const output = `${CACHE_DIR}/prioritization.level-table.${lang}.svg`;
 79 |   const dep = "typ/prioritization.typ";
 80 | 
 81 |   // compiled = output exists and newer than dep
 82 |   // TODO: Improve cache
 83 |   const compiled = await fs.stat(output)
 84 |     .then(async (outStat) => {
 85 |       const depStat = await fs.stat(dep).catch(() => null);
 86 |       if (!depStat) return false;
 87 |       return outStat.mtime > depStat.mtime;
 88 |     })
 89 |     .catch(() => false);
 90 |   if (compiled) {
 91 |     return;
 92 |   }
 93 | 
 94 |   const svg = await typst([
 95 |     "compile",
 96 |     "-",
 97 |     "-",
 98 |     "--format=svg",
 99 |     `--root=${ROOT_DIR}`,
100 |     ...extraArgs.pre,
101 |   ], {
102 |     stdin: `
103 | #set page(height: auto, width: auto, margin: 0.5em, fill: none)
104 | #import "/typ/prioritization.typ": level-table
105 | #level-table(lang: "${lang}")
106 | `.trim(),
107 |     color: color,
108 |   });
109 | 
110 |   // Support dark theme
111 |   const final = svg.replaceAll(
112 |     / (fill|stroke)="#000000"/g,
113 |     ' $1="currentColor"',
114 |   );
115 | 
116 |   await fs.writeFile(output, final);
117 | }
118 | 
119 | if (process.argv[1] === fileURLToPath(import.meta.url)) {
120 |   const argv = process.argv.slice(2);
121 |   const watchMode = ["--watch", "-w"].some((sw) => argv.includes(sw));
122 | 
123 |   if (watchMode) {
124 |     // We estimate which files could affect the compilation
125 |     const glob = watch(["{index,main}.typ", "typ/**/*"], {
126 |       persistent: true,
127 |       ignorePermissionErrors: true,
128 |     });
129 | 
130 |     const tryPrecompile = async () => {
131 |       try {
132 |         await precompile({ color: "always" });
133 |       } catch (error) {
134 |         console.error("💥 Precompilation failed:", error);
135 |       }
136 |     };
137 | 
138 |     glob.on("change", async (_event, path) => {
139 |       console.log("Refresh precompilation because of", path);
140 |       await tryPrecompile();
141 |     });
142 |     await tryPrecompile();
143 |   } else {
144 |     await precompile();
145 |   }
146 | }
147 | 


--------------------------------------------------------------------------------
/src/anchor-redirect.ts:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Redirect old anchors (`id` attributes) to the current ones.
 3 |  */
 4 | 
 5 | /** A map from old anchors to current anchors. */
 6 | const REDIRECTS: Record = {
 7 |   // Initial normalization
 8 |   "#x1-text-direction": "#direction",
 9 |   "#x1-1-writing-mode": "#writing-mode",
10 |   "#vertical-writing-mode": "#vertical",
11 |   "#x2-glyph-shaping-positioning": "#h-shaping",
12 |   "#x2-1-fonts-selection": "#font-select",
13 |   "#writing-chinese-without-configuring-any-font-leads-to-messy-font-fallback": "#font-fallback",
14 |   "#wrong-monospace-font-fallback-for-chinese-in-raw-block": "#font-fallback-raw",
15 |   "#wrong-font-fallback-for-chinese-in-math-equations": "#font-fallback-math",
16 |   "#language-dependant-font-configuration": "#lang-font",
17 |   "#size-per-font": "#per-font-size",
18 |   "#unable-to-infer-the-writing-script-across-elements-making-locl-sometimes-ineffective-locl": "#across-element-script",
19 |   "#x2-3-context-based-shaping-and-positioning": "#glyphs",
20 |   "#fake-synthesized-bold": "#synthesized-bold",
21 |   "#x2-6-case-other-character-transforms": "#transforms",
22 |   "#x3-typographic-units": "#h-units",
23 |   "#x3-1-characters-encoding": "#encoding",
24 |   "#ideographic-variation-sequence-disappears-at-end-of-line": "#ivs-line-end",
25 |   "#links-containing-non-ascii-characters-are-wrong-when-viewing-pdf-in-safari-ascii-safari-pdf": "#link-encoding",
26 |   "#x3-2-grapheme-word-segmentation-selection": "#segmentation",
27 |   "#x4-punctuation-inline-features": "#h-inline",
28 |   "#x4-1-phrase-section-boundaries": "#punctuation-etc",
29 |   "#quotation-marks-should-have-different-widths-for-chinese-and-western-text": "#quotation-mark-width",
30 |   "#x4-3-emphasis-highlighting": "#emphasis",
31 |   "#underline-breaks-when-mixing-chinese-and-western-text": "#underline-misalign",
32 |   "#add-support-for-ruby-cjk-e-g-furigana-for-japanese": "#pinyin",
33 |   "#x4-6-text-decoration-other-inline-features": "#text-decoration",
34 |   "#x4-7-data-formats-numbers": "#data-formats",
35 |   "#numbers-in-simplified-chinese": "#number-simplified",
36 |   "#numbers-in-traditional-chinese": "#number-traditional",
37 |   "#x5-line-and-paragraph-layout": "#h-lines-and-paragraphs",
38 |   "#interpuncts-should-not-appear-at-line-start": "#interpunct-line-start",
39 |   "#cjk-latin-glues-stretch-only-before-latin-characters": "#cjk-latin-stretch-before",
40 |   "#strict-grid-aligned-in-both-horizontal-and-vertical-axes": "#strict-2d-grid",
41 |   "#two-em-dashes-should-not-be-overhung": "#two-em-dash-overhung",
42 |   "#customize-punctuation-overhang": "#customize-overhang",
43 |   "#parenthetical-indication-punctuation-marks-at-the-start-of-paragraphs-are-not-adjusted-sometimes": "#paren-par-start",
44 |   "#unexpected-indentation-after-figures-lists-and-block-equations": "#indent-after-block",
45 |   "#even-inter-character-spacing": "#even-spacing",
46 |   "#x5-3-text-spacing": "#spacing",
47 |   "#cjk-latin-spacing-not-working-around-raw-raw": "#cjk-latin-around-raw",
48 |   "#cjk-latin-spacing-not-working-around-inline-equations": "#cjk-latin-around-math",
49 |   "#redundant-cjk-latin-space-at-manual-line-breaks": "#cjk-latin-manual-linebreak",
50 |   "#punctuation-compression-is-interrupted-by-show-show": "#show-interrupt-punct",
51 |   "#x5-4-baselines-line-height-etc": "#baselines",
52 |   "#default-line-height-is-too-tight-for-chinese": "#default-line-height",
53 |   "#box-is-not-aligned-if-text-bottom-edge-is-not-baseline-text-bottom-edge-box": "#box-align-bottom-edge",
54 |   "#x5-5-lists-counters-etc": "#lists",
55 |   "#list-and-enum-markers-are-not-aligned-with-the-baseline-of-the-item-s-contents-list-enum": "#list-enum-marker-align",
56 |   "#too-wide-spacing-between-heading-numbering-and-title": "#heading-spacing-to-numbering",
57 |   "#the-auto-hanging-indents-of-multiline-headings-are-inaccurate": "#heading-hanging-indent",
58 |   "#x6-page-book-layout": "#h-pages",
59 |   "#chinese-size-system-hao-system": "#zihao",
60 |   "#directly-setting-the-width-of-the-type-area-instead-of-the-paper-width": "#type-area-width",
61 |   "#x6-4-page-headers-footers-etc": "#headers-footers",
62 |   "#x6-5-forms-user-interaction": "#interaction",
63 |   "#x7-bibliography": "#bibliography",
64 |   "#x7-1-citing": "#cite",
65 |   "#citation-numbers-are-flying-over-their-brackets": "#cite-number-flying",
66 |   "#compression-of-continuous-citation-numbers": "#cite-number-compress",
67 |   "#superscript-and-non-superscript-forms-should-coexist": "#paren-cite",
68 |   "#cite-with-page-numbers": "#cite-page-number",
69 |   "#x7-2-bibliography-listing": "#bib-list",
70 |   "#use-et-al-for-english-and-for-chinese-et-al": "#et-al-lang",
71 |   "#institution-and-school-are-not-shown-institution-school": "#publisher-alias",
72 |   "#discontinuous-page-numbers-are-displayed-incorrectly-missing-a-comma": "#cite-discontinuous-page",
73 |   "#chinese-works-should-be-ordered-by-the-pinyin-or-strokes-of-the-authors-for-gb-7714-2015-author-date-gb-7714-2015-author-date": "#bib-order",
74 |   "#gb-7714-2015-note-is-totally-broken-gb-7714-2015-note": "#bib-note",
75 |   "#x7-3-bibliography-file": "#bib-file",
76 |   "#standard-is-not-correctly-interpreted-standard": "#bib-standard-misc",
77 |   "#failed-to-load-some-csl-styles-csl": "#csl-load",
78 |   "#x8-other": "#h-other",
79 |   "#x8-1-culture-specific-features": "#culture-specific",
80 |   "#for-references-to-headings-the-supplement-should-not-be-put-before-the-number": "#ref-number-supplement",
81 |   "#bilingual-figure-captions": "#bilingual-caption",
82 |   "#x8-2-what-else": "#other",
83 |   "#ignore-linebreaks-between-cjk-characters-in-source-code-cjk": "#ignore-linebreak",
84 |   "#internationalize-warning-and-error-messages": "#i18n-diag",
85 |   "#a-chinese-name-for-the-typst-project-typst": "#chinese-name",
86 |   "#web-app-issues": "#webapp-issues",
87 | };
88 | 
89 | function replaceAnchor(): void {
90 |   const old = window.location.hash;
91 |   if (old in REDIRECTS) {
92 |     window.location.hash = REDIRECTS[old];
93 |   }
94 | }
95 | 
96 | replaceAnchor();
97 | window.addEventListener("hashchange", replaceAnchor);
98 | 


--------------------------------------------------------------------------------
/src/respec/sidebar.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * The following script is copied from W3C/ReSpec under CC0-1.0 license
  3 |  * https://github.com/speced/bikeshed/blob/527e9641607d686e5c439f9999d40360607ee792/bikeshed/spec-data/readonly/boilerplate/footer.include
  4 |  * https://www.w3.org/scripts/TR/2021/fixup.js
  5 |  */
  6 | 
  7 | const tocToggleId = "toc-toggle";
  8 | const tocJumpId = "toc-jump";
  9 | const tocCollapseId = "toc-collapse";
 10 | const tocExpandId = "toc-expand";
 11 | 
 12 | interface CreatedElements {
 13 |   /** The button that toggles ToC sidebar, `#{tocToggleId}` */
 14 |   toggle: HTMLAnchorElement;
 15 | }
 16 | 
 17 | const t = {
 18 |   collapseSidebar: "Collapse Sidebar",
 19 |   expandSidebar: "Pop Out Sidebar",
 20 |   jumpToToc: "Jump to Table of Contents",
 21 | };
 22 | const collapseSidebarText = '← ' +
 23 |   `${t.collapseSidebar}`;
 24 | const expandSidebarText = '→ ' +
 25 |   `${t.expandSidebar}`;
 26 | const tocJumpText = '↑ ' +
 27 |   `${t.jumpToToc}`;
 28 | 
 29 | /** `true` means toc-sidebar, `false` means toc-inline */
 30 | type SidebarStatus = boolean;
 31 | 
 32 | /** Matches if default to toc-sidebar, does not match if default to toc-inline */
 33 | const sidebarMedia = window.matchMedia("screen and (min-width: 78em)");
 34 | 
 35 | function toggleSidebar(
 36 |   { toggle }: CreatedElements,
 37 |   /** `SidebarStatus` to select the desired status, `undefined` to toggle between them */
 38 |   on: SidebarStatus | undefined = undefined,
 39 |   /** Whether to force to skip scroll */
 40 |   skipScroll: boolean = false,
 41 | ): SidebarStatus {
 42 |   if (on === undefined) {
 43 |     on = !document.body.classList.contains("toc-sidebar");
 44 |   }
 45 | 
 46 |   if (!skipScroll) {
 47 |     /* Don't scroll to compensate for the ToC if we're above it already. */
 48 |     let headY = 0;
 49 |     const head = document.querySelector(".head");
 50 |     if (head) {
 51 |       // terrible approx of "top of ToC"
 52 |       headY += head.offsetTop + head.offsetHeight;
 53 |     }
 54 |     skipScroll = window.scrollY < headY;
 55 |   }
 56 | 
 57 |   const tocNav = document.getElementById("toc") as HTMLElement;
 58 |   if (on) {
 59 |     document.body.classList.add("toc-sidebar");
 60 |     document.body.classList.remove("toc-inline");
 61 | 
 62 |     toggle.innerHTML = collapseSidebarText;
 63 |     toggle.setAttribute("aria-labelledby", `${tocCollapseId}-text`);
 64 | 
 65 |     if (!skipScroll) {
 66 |       const tocHeight = tocNav.offsetHeight;
 67 |       window.scrollBy(0, 0 - tocHeight);
 68 |     }
 69 | 
 70 |     tocNav.focus();
 71 |   } else {
 72 |     document.body.classList.add("toc-inline");
 73 |     document.body.classList.remove("toc-sidebar");
 74 | 
 75 |     toggle.innerHTML = expandSidebarText;
 76 |     toggle.setAttribute("aria-labelledby", `${tocExpandId}-text`);
 77 | 
 78 |     if (!skipScroll) {
 79 |       window.scrollBy(0, tocNav.offsetHeight);
 80 |     }
 81 | 
 82 |     if (toggle.matches(":hover")) {
 83 |       /* Unfocus button when not using keyboard navigation,
 84 |          because I don't know where else to send the focus. */
 85 |       toggle.blur();
 86 |     }
 87 |   }
 88 | 
 89 |   return on;
 90 | }
 91 | 
 92 | function createSidebarToggle(): CreatedElements {
 93 |   /* Create the sidebar toggle in JS; it shouldn't exist when JS is off. */
 94 |   const toggle = document.createElement("a");
 95 |   /* This should probably be a button, but appearance isn't standards-track.*/
 96 |   toggle.id = tocToggleId;
 97 |   toggle.classList.add("toc-toggle");
 98 |   toggle.href = "#toc";
 99 |   toggle.innerHTML = collapseSidebarText;
100 |   toggle.setAttribute("aria-labelledby", `${tocCollapseId}-text`);
101 | 
102 |   /* Get , or make it if we don't have one. */
103 |   let tocNav = document.getElementById("toc-nav");
104 |   if (!tocNav) {
105 |     tocNav = document.createElement("p");
106 |     tocNav.id = "toc-nav";
107 |     /* Prepend for better keyboard navigation */
108 |     document.body.insertBefore(tocNav, document.body.firstChild);
109 |   }
110 | 
111 |   /* While we're at it, make sure we have a Jump to Toc link. */
112 |   let tocJump = document.getElementById(tocJumpId) as HTMLAnchorElement | null;
113 |   if (!tocJump) {
114 |     tocJump = document.createElement("a");
115 |     tocJump.id = tocJumpId;
116 |     tocJump.href = "#toc";
117 |     tocJump.innerHTML = tocJumpText;
118 |     tocJump.setAttribute("aria-labelledby", `${tocJumpId}-text`);
119 |     tocNav.appendChild(tocJump);
120 |   }
121 | 
122 |   tocNav.appendChild(toggle);
123 | 
124 |   return { toggle };
125 | }
126 | 
127 | function setupToggleListener({ toggle }: CreatedElements): void {
128 |   const toggleToDefault = (e: MediaQueryListEvent): void => {
129 |     toggleSidebar({ toggle }, e.matches);
130 |   };
131 | 
132 |   // Toggle the sidebar to the default state at start up
133 |   // Force to skip scroll because it will be the first view
134 |   toggleSidebar({ toggle }, sidebarMedia.matches, true);
135 | 
136 |   // Listen to width changes, and auto-collapse when out of room
137 |   sidebarMedia.addEventListener("change", toggleToDefault);
138 | 
139 |   // Toggle the sidebar when clicked
140 |   toggle.addEventListener("click", (e) => {
141 |     e.preventDefault();
142 | 
143 |     // Persist explicit off states
144 |     sidebarMedia.removeEventListener("change", toggleToDefault);
145 | 
146 |     // Toggle the sidebar
147 |     const finallyOn = toggleSidebar({ toggle });
148 | 
149 |     // If the sidebar is finally on, auto-collapse when out of room later
150 |     if (finallyOn) {
151 |       sidebarMedia.addEventListener("change", toggleToDefault);
152 |     }
153 | 
154 |     return false;
155 |   }, false);
156 | }
157 | 
158 | export default function (): void {
159 |   const toc = document.getElementById("toc");
160 |   if (!toc) {
161 |     console.warn(
162 |       "Can't find Table of Contents. Please use  around the ToC.",
163 |     );
164 |     return;
165 |   }
166 | 
167 |   const created = createSidebarToggle();
168 |   setupToggleListener(created);
169 | 
170 |   /* If the sidebar has been manually opened and is currently overlaying the text
171 |      (window too small for the MQ to add the margin to body),
172 |      then auto-close the sidebar once you click on something in there. */
173 |   toc.addEventListener("click", (e) => {
174 |     if (
175 |       document.body.classList.contains("toc-sidebar") && !sidebarMedia.matches
176 |     ) {
177 |       let el = e.target as HTMLElement;
178 |       while (el != toc) { // find closest 
179 |         if (el.tagName.toLowerCase() === "a") {
180 |           toggleSidebar(created, false);
181 |           return;
182 |         }
183 |         el = el.parentElement!;
184 |       }
185 |     }
186 |   }, false);
187 | }
188 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # [clreq](https://www.w3.org/TR/clreq/)-[gap](https://www.w3.org/TR/clreq-gap/) for [typst](https://typst.app/home)
  2 | 
  3 | Chinese Layout Gap Analysis for Typst.
  4 | 分析 Typst 与中文排版的差距。
  5 | 
  6 | [![Check](https://github.com/typst-doc-cn/clreq/actions/workflows/check.yml/badge.svg)](https://github.com/typst-doc-cn/clreq/actions/workflows/check.yml)
  7 | [![Website](https://img.shields.io/website?url=https%3A%2F%2Ftypst-doc-cn.github.io%2Fclreq%2F&label=Website)](https://typst-doc-cn.github.io/clreq/)
  8 | 
  9 | **语言版本：[English](./README.en.md)** | **[中文（当前文件）](./README.md)**
 10 | 
 11 | 
 12 | Typst 是一款基于标记的排版软件，这份文档描述了它在中文支持方面的差距，特别是[排版](https://www.w3.org/TR/clreq/)和[参考文献著录](https://std.samr.gov.cn/gb/search/gbDetailed?id=71F772D8055ED3A7E05397BE0A0AB82A)。本文会检查 typst 编译器是否支持所需功能，并介绍可能的临时解决方案。
 13 | 
 14 | 
 15 | [文档正文位于网站](https://typst-doc-cn.github.io/clreq/)，以下是参与指南。
 16 | 
 17 | ## 参与指南
 18 | 
 19 | ### 反馈
 20 | 
 21 | 如果您发现缺漏错误，或有疑问建议，请在 [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/) 提出。
 22 | 
 23 | - 语言：这里使用中英文均可。待时机成熟后，会用英文反馈给 [Typst 官方](https://github.com/typst/typst/)，同时在此文档补全双语翻译。
 24 | 
 25 | - 若是初次使用，可参考 [W3C 的 GitHub Issue 指南（附图，中文）](https://www.w3.org/International/i18n-activity/guidelines/issues.zh-hans.html)。如果有困难，也可加入 [QQ 中文聊天群](https://typst-doc-cn.github.io/guide/#用户社区)直接反馈。
 26 | 
 27 | ### 编辑文档
 28 | 
 29 | 文档正文使用 Typst 生成。日常编辑方法如下：
 30 | 
 31 | 1. [在 GitHub 上打开`main.typ`](https://github.com/typst-doc-cn/clreq/blob/main/main.typ)
 32 | 2. 单击右上角的编辑按钮`✏️`，按提示进行准备工作（登录、创建 fork 等）。
 33 | 3. 编辑`main.typ`。
 34 | 4. 单击右上角 _Commit changes…_，按提示完成编辑（简要介绍修改，发起 pull request 等）。
 35 | 5. 稍等片刻，机器人会将新版文档渲染成网页，评论到 pull request 下。可视情况继续编辑。
 36 | 
 37 | 
 38 | 也可在本地预览
 39 | 
 40 | ```shell
 41 | # 编译
 42 | pnpm build # ⇒ dist/index.html
 43 | 
 44 | # 跟踪更改自动重新编译
 45 | pnpm dev --open # ⇒ http://localhost:3000
 46 | ```
 47 | 
 48 | 需要预先安装：
 49 | 
 50 | - [pnpm](https://pnpm.io)，包管理器
 51 | 
 52 | - _Noto Serif CJK SC_，字体
 53 | 
 54 |   1. 从[校园网联合镜像站 · Google Fonts](https://mirrors.cernet.edu.cn/font/GoogleFonts)
 55 |   下载[`09_NotoSerifCJKsc.zip`](https://mirrors.cernet.edu.cn/github-release/googlefonts/noto-cjk/LatestRelease/09_NotoSerifCJKsc.zip)，或者从
 56 |   [GitHub Releases · notofonts/noto-cjk](https://github.com/notofonts/noto-cjk/releases)
 57 |   下载 [Language Specific OTFs Simplified Chinese (简体中文)](https://github.com/notofonts/noto-cjk/releases/latest/download/09_NotoSerifCJKsc.zip)。
 58 | 
 59 |   2. 把字体安装到系统中，或者把字体文件放到`./fonts/`。
 60 | 
 61 |   对于大多数贡献者，只安装 _Noto Serif CJK SC_ 就够了。如需严格复现所有例子，请参考[`download_fonts.sh`](./scripts/download_fonts.sh)。
 62 | 
 63 | 
 64 | 
 65 | ## `main.typ`编写参考
 66 | 
 67 | ### 内容范围
 68 | 
 69 | 对于每个问题，请尽量：
 70 | 
 71 | - 简要描述问题
 72 | 
 73 | - 提供能一眼看懂问题的简洁例子
 74 | 
 75 | - 补充不懂中文者可能不清楚的背景
 76 | 
 77 |   例如，写中文需要输入法。可链接 [Unicode 中文日文 FAQ](https://unicode.org/faq/han_cjk.html)。
 78 | 
 79 | 不过一般：
 80 | 
 81 | - 无需直接提供解决方案
 82 | 
 83 |   只要`#workaround("https://…")`这样链接即可。
 84 | 
 85 | - 无需全面描述问题，也不建议过多讨论改进方案
 86 | 
 87 |   这些内容可初步在 [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/) 提出，最终应反馈给 Typst 官方。
 88 | 
 89 | ### 维护更新
 90 | 
 91 | GitHub Actions 会监控文档中标记的`#issue`和`#pull`，发现状态变化就会在 [🤖 Cron check · Issue #22](https://github.com/typst-doc-cn/clreq/issues/22) 和 pull request 提醒。
 92 | 
 93 | 收到提醒即可更新文档，不必等到 Typst 发布新版本。
 94 | 
 95 | 更新示例如下。
 96 | 
 97 | ```diff
 98 | - #level.basic
 99 | + #level.ok
100 | - #issue("typst#633")
101 | - #pull("typst#5777")
102 | + #issue("typst#633", closed: true)
103 | + #pull("typst#5777", merged: true)
104 |   #workaround("https://typst-doc-cn.github.io/guide/FAQ/cite-flying.html")
105 | +
106 | + #till-next(now-fixed.with(last-affected: "0.13.1", last-level: "basic"))
107 | ```
108 | 
109 | ### 多语言内容（`babel`/`bbl`）
110 | 
111 | - `en`、`zh`两字段分别在 English、中文模式显示。
112 | 
113 | - `babel`用于段落`par`，会生成块级元素（``）；`bbl`用于段落内的短语短句，会生成行内元素（``）。
114 | 
115 | 示例：
116 | 
117 | ```typst
118 | === #bbl(en: [Vertical Writing Mode], zh: [直排])
119 | 
120 | #babel(
121 |   en: [There are *two* writing modes in Chinese composition…],
122 |   zh: [中文有*两种*行文模式……],
123 | )
124 | ```
125 | 
126 | 提示：
127 | 
128 | - 打 pull request 草稿时，不必一开始就写全双语翻译；可先只写一种，敲定内容后再补另一种。
129 | 
130 | - 不是所有内容都要翻译。某些术语无法翻译，或者只看单一语言会有歧义，这种就没必要套`bbl`，直接写即可。
131 | 
132 | - 不用刻意关注换行与缩进，按 tinymist (VS Code) / typstyle 默认即可。为方便对比版本，已设置 pull request 机器人自动统一格式。
133 | 
134 | ### 标题格式
135 | 
136 | - 表示**分类**的大章节
137 | 
138 |   标题尽量与 [W3C 差距分析文档](https://www.w3.org/TR/clreq-gap/)保持一致。
139 | 
140 | - 描述**具体差距**的小章节
141 | 
142 |   - 对于需要支持但**尚不支持**的功能，标题尽量用**短语**表达。
143 | 
144 |     示例：
145 | 
146 |     - Vertical writing mode | 直排
147 |     - Customizing punctuation overhang | 定制标点悬挂
148 | 
149 |   - 对于**已支持**功能存在的问题，标题尽量用**句子**表达。
150 | 
151 |     示例：
152 | 
153 |     - Spacing between heading numbering and title is too wide | 标题编号与内容之间的空隙过宽
154 |     - Citation numbers are flying over their brackets | 引用编号的数字高于括号
155 | 
156 |   - 差距解决之后，尽量不再修改标题。
157 | 
158 | ### 添加代码例子
159 | 
160 | 代码例子会在渲染网站时编译。
161 | 
162 | 编写代码例子时：
163 | 
164 | - 应保证与显示语言无关，不支持也不能使用`babel`
165 | 
166 | - 占位内容优先用汉字，只有必要时才加上标点和拉丁字母
167 | 
168 | - 尽量避免在代码内包含说明性文字；若实在无法避免，优先用英文短语或 emoji
169 | 
170 | 添加例子的具体方法是插入代码块，并标注代码语言为以下某一项。以下分类介绍。
171 | 
172 | #### Simple examples (`example`)
173 | 
174 | 简单 Typst 例子。
175 | 
176 | ````typst
177 | ```example
178 | >>> Current: \
179 | #underline[中文和English]
180 | 
181 | >>> Expected: \
182 | >>> #set underline(offset: .15em, stroke: .05em)
183 | >>> #underline[中文和English]
184 | ```
185 | ````
186 | 
187 | - 普通行：
188 | 
189 |   👀 显示到源代码，并 🚀 执行成预览结果。
190 | 
191 | - `>>>`打头的行：
192 | 
193 |   🙈 在源代码中隐藏，但仍然 🚀 执行成预览结果。
194 | 
195 | - `<<< `打头的行：
196 | 
197 |   👀 显示到源代码，但 🛑 不会执行成预览结果。
198 | 
199 | ##### 缺点与限制
200 | 
201 | simple example 执行于容器中，且会在整篇文档中共享状态。
202 | 
203 | 因此：
204 | 
205 | - 不支持页面设置。
206 | 
207 |   若只需`#set page(width: …)`，可换用`#show: block.with(width: …)`。
208 | 
209 | - 更新计数器会影响后续例子。
210 | 
211 | - 引用与参考文献会与其它例子冲突。
212 | 
213 | - 设置的默认值会按`raw`，可能与普通文档不同。
214 | 
215 |   例如，`text.cjk-latin-spacing`一般默认为`auto`，但这里是`none`。
216 | 
217 | - 标题等样式会受文档全局样式影响。
218 | 
219 | - ……
220 | 
221 | 如需高级功能或 100% 准确，请换用 page example。
222 | 
223 | #### Page examples (`example-page`)
224 | 
225 | 编译成单独页面的 Typst 例子。
226 | 
227 | `````typst
228 | ````example-page
229 | >>> Current: \
230 | 孔乙己@key
231 | 
232 | >>> Expected: \
233 | >>> 孔乙己@key
234 | >>> #show bibliography: none
235 | #let bib = ```bib
236 | @misc{key,
237 |   title = {Title},
238 | }
239 | ```.text
240 | #bibliography(bytes(bib), style: "gb-7714-2015-numeric")
241 | ````
242 | `````
243 | 
244 | `<<< `与`>>>`的意义与 simple example 相同。
245 | 
246 | #### Bibliography examples (`example-bib`)
247 | 
248 | 参考文献著录例子。
249 | 
250 | ````typst
251 | ```example-bib
252 | @book{key,
253 |   title = {标题},
254 |   author = {作者},
255 |   year = {2025}
256 | }
257 | % 作者. 标题. 2025.
258 | ```
259 | ````
260 | 
261 | - 普通行：BibTeX 项目。
262 | 
263 | - `%`打头的行：预期输出。
264 | 
265 | ## 许可
266 | 
267 | 除非另有说明，代码按 Apache 2.0 许可。其它内容暂时保留权利。
268 | 


--------------------------------------------------------------------------------
/typ/util.typ:
--------------------------------------------------------------------------------
  1 | #import "@preview/unichar:0.3.0": codepoint
  2 | 
  3 | #import "icon.typ"
  4 | #import "templates/html-fix.typ": link-in-new-tab
  5 | #import "prioritization.typ": config as priority-config
  6 | 
  7 | /// Multilingual
  8 | #let _babel(en: [], zh: [], tag: "span") = {
  9 |   // Add “todo”
 10 |   if int(en != []) + int(zh != []) >= 1 {
 11 |     if zh == [] {
 12 |       zh = [TODO: 待译]
 13 |     }
 14 |     if en == [] {
 15 |       en = [TODO: to be translated]
 16 |     }
 17 |   }
 18 | 
 19 |   set text(lang: "en")
 20 |   html.elem(tag, en, attrs: (lang: "en", its-locale-filter-list: "en"))
 21 | 
 22 |   if tag == "span" { [ ] }
 23 | 
 24 |   set text(lang: "zh", region: "CN")
 25 |   html.elem(tag, zh, attrs: (lang: "zh-Hans", its-locale-filter-list: "zh"))
 26 | }
 27 | /// For paragraphs
 28 | #let babel = _babel.with(tag: "p")
 29 | /// For headings
 30 | #let bbl = _babel.with(tag: "span")
 31 | 
 32 | 
 33 | /// Link to a GitHub issue
 34 | ///
 35 | /// - repo-num (str): Repo and issue number, e.g., `"typst#193"`, `"hayagriva#189"`
 36 | /// - anchor (str): Anchor in the page, e.g., `"#issuecomment-1855739446"`
 37 | /// - note (content): Annotation
 38 | /// - closed (bool): State of the issue
 39 | /// -> content
 40 | #let issue(repo-num, anchor: "", note: auto, closed: false) = {
 41 |   let (repo, num) = repo-num.split("#")
 42 |   if not repo.contains("/") {
 43 |     repo = "typst/" + repo
 44 |   }
 45 | 
 46 |   show link: link-in-new-tab.with(class: "unbreakable")
 47 |   link("https://github.com/" + repo + "/issues/" + num + anchor, {
 48 |     if closed { icon.issue-closed } else { icon.issue-open }
 49 |     repo-num
 50 |     if note == auto {
 51 |       if anchor != "" { [~(comment)] }
 52 |     } else { [~(#note)] }
 53 |   })
 54 |   [#metadata((repo: repo, num: num, note: repr(note), closed: closed))]
 55 | }
 56 | 
 57 | /// Link to a GitHub pull request
 58 | ///
 59 | /// - repo-num (str): Repo and pull request number, e.g., `"typst#5777"`
 60 | /// - merged (bool): Whether the pull request is merged
 61 | /// - rejected (bool): Whether the pull request is rejected (closed but not merged)
 62 | /// -> content
 63 | #let pull(repo-num, merged: false, rejected: false) = {
 64 |   assert.ne((merged, rejected), (true, true), message: "a pull request cannot be both merged and rejected")
 65 | 
 66 |   let (repo, num) = repo-num.split("#")
 67 |   if not repo.contains("/") {
 68 |     repo = "typst/" + repo
 69 |   }
 70 | 
 71 |   show link: link-in-new-tab.with(class: "unbreakable")
 72 |   link("https://github.com/" + repo + "/pull/" + num, {
 73 |     if merged { icon.git-merge } else if rejected { icon.git-pull-request-closed } else { icon.git-pull-request }
 74 |     repo-num
 75 |   })
 76 |   [#metadata((repo: repo, num: num, merged: merged, rejected: rejected))]
 77 | }
 78 | 
 79 | /// Link to a workaround
 80 | ///
 81 | /// - dest (str): URL
 82 | /// - note (content): Annotation
 83 | /// -> content
 84 | #let workaround(dest, note: none) = {
 85 |   let human-dest = if dest.starts-with("https://typst.app/universe/package/") {
 86 |     "universe/" + dest.trim("https://typst.app/universe/package/", at: start)
 87 |   } else if dest.starts-with("https://typst-doc-cn.github.io/guide/FAQ/") {
 88 |     "Chinese FAQ"
 89 |   } else {
 90 |     dest.trim("https://", at: start).split(".").at(0).trim("typst-", at: start)
 91 |   }
 92 | 
 93 |   let body = if note == none {
 94 |     [fix (#human-dest)]
 95 |   } else {
 96 |     [fix (#human-dest, #note)]
 97 |   }
 98 | 
 99 |   show link: link-in-new-tab.with(class: "unbreakable")
100 |   link(dest, {
101 |     icon.light-bulb
102 |     body
103 |   })
104 |   [#metadata((dest: dest, note: note))]
105 | }
106 | 
107 | /// A formatted description of the Unicode character for a given codepoint
108 | ///
109 | /// Usage: `unichar("‘")`
110 | #let unichar(code) = html.span(class: "unichar", {
111 |   let c = codepoint(code)
112 | 
113 |   show smallcaps: html.span.with(class: "small-caps")
114 | 
115 |   html.span(class: "code-point")[U+#lower(c.id)]
116 |   [~]
117 |   raw(str.from-unicode(c.code))
118 |   [ ]
119 |   smallcaps(lower(c.name))
120 | })
121 | 
122 | /// Introduction of a section
123 | ///
124 | /// If it is derived from #link("https://github.com/w3c/i18n-activity/blob/5cfa8e5d304c8db0473562defab7032d90217f1b/templates/gap-analysis/prompts.js")[W3C i18n-activity gap-analysis prompts],
125 | /// then provide the URL as `from-w3c`.
126 | ///
127 | /// - from-w3c (str): URL to the original W3C prompt, if applicable.
128 | /// - body (content):
129 | /// -> content
130 | #let prompt(from-w3c: none, body) = html.article(
131 |   class: "prompt",
132 |   {
133 |     body
134 | 
135 |     if from-w3c != none {
136 |       html.p(class: "license")[
137 |         #show link: link-in-new-tab
138 |         #bbl(
139 |           en: [(derived from #link(from-w3c)[a W3C document] under #html.a(target: "_blank", href: "https://www.w3.org/copyright/software-license-2023/", title: "Software and Document License")[its license])],
140 |           zh: [（按#html.a(target: "_blank", href: "https://www.w3.org/zh-hans/copyright/software-license-2023/", title: "软件和文档许可协议")[相应协议]修改自 #link(from-w3c)[W3C 文档]）],
141 |         )
142 |       ]
143 |     }
144 |   },
145 | )
146 | 
147 | /// A side note
148 | ///
149 | /// - summary (content): A short summary of the note
150 | /// - body (content):
151 | /// -> content
152 | #let note(summary: bbl(en: [Note], zh: [注]), body) = html.aside(class: "note", role: "note", {
153 |   html.p(class: "note-title", {
154 |     icon.comment
155 |     summary
156 |   })
157 | 
158 |   body
159 | })
160 | 
161 | /// An issue that is now fixed
162 | ///
163 | /// - last-affected (str): The last affected version, e.g. `"0.13.1"`
164 | /// - last-level (str): Previous priority level
165 | /// - body (content):
166 | /// -> content
167 | #let now-fixed(last-affected: none, last-level: none, body) = {
168 |   assert.ne(last-affected, none, message: "the `last-affected` version should be specified, e.g. `\"0.13.1\"`")
169 |   last-affected = version(last-affected.split(".").map(int))
170 | 
171 |   assert(
172 |     last-level in priority-config.keys(),
173 |     message: "`last-level` should be a level in " + repr(priority-config.keys()),
174 |   )
175 |   last-level = priority-config.at(last-level)
176 | 
177 |   let already-fixed = sys.version > last-affected
178 | 
179 |   html.details(
180 |     class: "now-fixed",
181 |     open: not already-fixed,
182 |     {
183 |       html.summary(html.p(if already-fixed {
184 |         bbl(
185 |           en: [Now fixed! (it was #last-level.human in v#last-affected)],
186 |           zh: [现已修复！（v#last-affected 曾为 #last-level.human）],
187 |         )
188 |       } else {
189 |         bbl(
190 |           en: [Fixed in dev! (it is #last-level.human in v#last-affected)],
191 |           zh: [已于开发版修复！（v#last-affected 为 #last-level.human）],
192 |         )
193 |       }))
194 | 
195 |       if already-fixed {
196 |         babel(
197 |           en: [#emoji.warning The following description was written for typst v#last-affected, but the examples are rendered in v#sys.version. Results may differ.],
198 |           zh: [#emoji.warning 以下描述针对 typst v#last-affected，但例子采用 v#sys.version 渲染，结果可能不一致。],
199 |         )
200 |       }
201 | 
202 |       body
203 |     },
204 |   )
205 | }
206 | 


--------------------------------------------------------------------------------
/src/global.css:
--------------------------------------------------------------------------------
  1 | /*
  2 |   Edit from astro’s global.css.
  3 |   https://github.com/withastro/astro/blob/c46210d8db9e88bd6b316be779809f0e44715030/examples/blog/src/styles/global.css
  4 | 
  5 |   The CSS in this style tag is based off of Bear Blog's default CSS.
  6 |   https://github.com/HermanMartinus/bearblog/blob/297026a877bc2ab2b3bdfbd6b9f7961c350917dd/templates/styles/blog/default.css
  7 |   License MIT: https://github.com/HermanMartinus/bearblog/blob/master/LICENSE.md
  8 |  */
  9 | 
 10 | :root {
 11 |   --main-color: #000;
 12 |   --main-hover-color: #222939;
 13 |   --raw-bg-color: rgba(101, 117, 133, 0.16);
 14 |   --main-bg-color: #fafcfc;
 15 |   --nav-bg-color: #fafcfc;
 16 |   --gray-color: #6d6d6d;
 17 |   --accent: oklch(51.51% .2307 257.85);
 18 |   --accent-dark: oklch(64.94% .1982 251.813);
 19 |   --black: #0f1219;
 20 | }
 21 | 
 22 | :root.dark {
 23 |   --main-color: #dfdfd6;
 24 |   --main-hover-color: #fff;
 25 |   --gray-color: #939da3;
 26 |   --raw-bg-color: #65758529;
 27 |   --main-bg-color: #212737;
 28 |   --nav-bg-color: #212737;
 29 |   --accent: oklch(71.7% .1648 250.794);
 30 |   --accent-dark: oklch(51.51% .2307 257.85);
 31 | }
 32 | 
 33 | html {
 34 |   scroll-behavior: smooth;
 35 | }
 36 | body {
 37 |   --vp-font-family-base: "Inter Variable", "Noto Sans SC", "PingFang SC",
 38 |     "Microsoft Yahei", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
 39 |     "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
 40 |   --vp-font-family-mono: ui-monospace, "Menlo", "Monaco", "Consolas",
 41 |     "Liberation Mono", "Courier New", monospace;
 42 | 
 43 |   font-family: var(--vp-font-family-base);
 44 |   margin: 0;
 45 |   padding: 0;
 46 |   background: var(--main-bg-color);
 47 |   background-size: 100% 600px;
 48 |   word-wrap: break-word;
 49 |   overflow-wrap: break-word;
 50 |   color: var(--main-color);
 51 |   line-height: 1.7;
 52 | }
 53 | main,
 54 | .search {
 55 |   max-width: min(56rem, calc(100% - 2em));
 56 |   margin: auto;
 57 | }
 58 | main {
 59 |   padding: 3em 1em;
 60 | }
 61 | @media (max-width: 720px) {
 62 |   main {
 63 |     padding: 1em;
 64 |   }
 65 |   body {
 66 |     text-align: left;
 67 |   }
 68 | }
 69 | :root {
 70 |   --heading-hash-offset-1: 1.75rem;
 71 |   --heading-hash-offset-2: 1.75rem;
 72 |   --heading-hash-offset-3: 1.75rem;
 73 |   --heading-hash-offset-4: 1.75rem;
 74 |   --heading-hash-offset-5: 1.75rem;
 75 | }
 76 | 
 77 | h1 :target,
 78 | h2 :target,
 79 | h3 :target,
 80 | h4 :target,
 81 | h5 :target,
 82 | h6 :target {
 83 |   scroll-margin-top: 1.25em;
 84 | }
 85 | h1 {
 86 |   font-size: 2.75em;
 87 |   margin-block-start: 0em;
 88 |   margin-block-end: 0.8888889em;
 89 |   margin-inline-start: 0px;
 90 |   margin-inline-end: 0px;
 91 |   line-height: 1.1111111;
 92 | }
 93 | h2 {
 94 |   font-size: 2em;
 95 |   margin-block-start: 1.6em;
 96 |   margin-block-end: 0.6em;
 97 |   margin-inline-start: 0px;
 98 |   margin-inline-end: 0px;
 99 |   line-height: 1.3333333;
100 | }
101 | h3 {
102 |   font-size: 1.5em;
103 |   margin-block-start: 1.5em;
104 |   margin-block-end: 0.6em;
105 |   margin-inline-start: 0px;
106 |   margin-inline-end: 0px;
107 |   line-height: 1.45;
108 | }
109 | h4 {
110 |   font-size: 1.25em;
111 |   margin-block-start: 1.5em;
112 |   margin-block-end: 0.6em;
113 |   margin-inline-start: 0px;
114 |   margin-inline-end: 0px;
115 |   line-height: 1.6;
116 | }
117 | h5 {
118 |   font-size: 1.1em;
119 |   margin-block-start: 1.5em;
120 |   margin-block-end: 0.5em;
121 |   margin-inline-start: 0px;
122 |   margin-inline-end: 0px;
123 |   line-height: 1.5;
124 | }
125 | h1, h2, h3, h4, h5, h6 {
126 |   text-align: start;
127 | }
128 | p {
129 |   margin-block-end: 0.5em;
130 | }
131 | strong,
132 | b {
133 |   font-weight: 700;
134 | }
135 | a,
136 | .link {
137 |   color: var(--accent);
138 |   text-decoration: underline;
139 |   cursor: pointer;
140 | }
141 | a,
142 | .link {
143 |   transition: color 0.1s, underline 0.1s;
144 | }
145 | a:hover,
146 | .link:hover {
147 |   color: var(--accent-dark);
148 |   text-decoration: underline solid 2px;
149 | }
150 | textarea {
151 |   width: 100%;
152 |   font-size: 16px;
153 | }
154 | input {
155 |   font-size: 16px;
156 | }
157 | table {
158 |   width: 100%;
159 | }
160 | img {
161 |   max-width: 100%;
162 |   height: auto;
163 |   border-radius: 8px;
164 | }
165 | pre,
166 | code,
167 | kbd,
168 | samp {
169 |   font-family: var(--vp-font-family-mono);
170 | }
171 | code {
172 |   padding: 2px 5px;
173 |   background-color: var(--raw-bg-color);
174 |   border-radius: 2px;
175 | }
176 | pre {
177 |   padding: 1.5em;
178 |   border-radius: 8px;
179 | }
180 | pre > code {
181 |   all: unset;
182 | }
183 | blockquote {
184 |   border-left: 4px solid var(--accent);
185 |   padding: 0 0 0 18px;
186 |   margin: 0px;
187 |   font-size: 1.333em;
188 | }
189 | hr {
190 |   border: none;
191 |   border-top: 1px solid var(--raw-bg-color);
192 | }
193 | 
194 | .sr-only {
195 |   border: 0;
196 |   padding: 0;
197 |   margin: 0;
198 |   position: absolute !important;
199 |   height: 1px;
200 |   width: 1px;
201 |   overflow: hidden;
202 |   /* IE6, IE7 - a 0 height clip, off to the bottom right of the visible 1px box */
203 |   clip: rect(1px 1px 1px 1px);
204 |   /* maybe deprecated but we need to support legacy browsers */
205 |   clip: rect(1px, 1px, 1px, 1px);
206 |   /* modern browsers, clip-path works inwards from each corner */
207 |   clip-path: inset(50%);
208 |   /* added line to stop words getting smushed together (as they go onto separate lines and some screen readers do not understand line feeds as a space */
209 |   white-space: nowrap;
210 | }
211 | nav a,
212 | .social-links a {
213 |   text-decoration: none;
214 |   color: var(--main-color);
215 | }
216 | nav a:hover,
217 | .social-links a:hover {
218 |   color: var(--main-hover-color);
219 | }
220 | .icon svg {
221 |   width: 32px;
222 |   height: 32px;
223 |   overflow: visible;
224 | }
225 | main .icon svg {
226 |   width: 1em;
227 |   height: 1em;
228 |   margin: 0.25em;
229 |   vertical-align: middle;
230 | }
231 | .icon svg path,
232 | .icon svg circle {
233 |   fill: currentColor;
234 | }
235 | .theme-icon {
236 |   cursor: pointer;
237 | }
238 | .dark .code-image.themed .light {
239 |   display: none;
240 | }
241 | .dark .code-image.themed .dark {
242 |   display: initial;
243 | }
244 | .code-image.themed .light {
245 |   display: initial;
246 | }
247 | .code-image.themed .dark {
248 |   display: none;
249 | }
250 | 
251 | figure {
252 |   margin-left: auto;
253 |   margin-right: auto;
254 |   text-align: center;
255 |   overflow-x: auto;
256 | }
257 | figure > img {
258 |   width: 40%;
259 | }
260 | @media (max-width: 720px) {
261 |   figure > img {
262 |     width: 60%;
263 |   }
264 | }
265 | figcaption {
266 |   text-align: center;
267 | }
268 | .code-image svg {
269 |   max-width: 100%;
270 |   height: fit-content;
271 | }
272 | .inline-equation {
273 |   display: inline-block;
274 |   width: fit-content;
275 |   margin: 0 0.15em;
276 | }
277 | .block-equation {
278 |   display: grid;
279 |   place-items: center;
280 |   overflow-x: auto;
281 | }
282 | .block-list,
283 | .block-list li {
284 |   margin: 0;
285 |   padding: 0;
286 | }
287 | .block-list > li {
288 |   list-style: none;
289 |   margin-top: 1.5em;
290 |   padding-left: 1em;
291 |   border-left: 2.5px solid var(--main-color);
292 | }
293 | .block-list.accent > li {
294 |   border-left: 2.5px solid var(--accent);
295 | }
296 | 


--------------------------------------------------------------------------------
/src/htmldiff-nav.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Mouse and keyboard navigation.
  3 |  *
  4 |  * Replace the original https://w3c.github.io/htmldiff-nav/index.js.
  5 |  * https://github.com/w3c/htmldiff-nav/blob/ab28ebba333cc88407da0621f046c8f10eed1d52/index.js
  6 |  *
  7 |  * # Changes
  8 |  *
  9 |  * - Remove features related to `.annoying-warning` or `script[data-navigable-selector]`.
 10 |  * - If the current change is in a ``, expand the ``.
 11 |  * - If a change is clicked, update internal states.
 12 |  */
 13 | 
 14 | class FocusState {
 15 |   private readonly changes: HTMLElement[];
 16 |   private index: number | null = null;
 17 |   private readonly size: number;
 18 | 
 19 |   constructor(changes: HTMLElement[]) {
 20 |     this.changes = changes;
 21 |     this.size = changes.length;
 22 |   }
 23 | 
 24 |   human_position(): string {
 25 |     return `${(this.index ?? -1) + 1} of ${this.size}`;
 26 |   }
 27 |   current(): HTMLElement | null {
 28 |     return this.index !== null ? this.changes[this.index] : null;
 29 |   }
 30 |   previous(): HTMLElement {
 31 |     if (this.index === null) {
 32 |       this.index = 0;
 33 |     } else {
 34 |       this.index--;
 35 |       if (this.index < 0) {
 36 |         this.index = this.size - 1;
 37 |       }
 38 |     }
 39 |     return this.changes[this.index];
 40 |   }
 41 |   next(): HTMLElement {
 42 |     if (this.index === null) {
 43 |       this.index = 0;
 44 |     } else {
 45 |       this.index++;
 46 |       if (this.index >= this.size) {
 47 |         this.index = 0;
 48 |       }
 49 |     }
 50 |     return this.changes[this.index];
 51 |   }
 52 |   stop(): void {
 53 |     this.index = null;
 54 |   }
 55 | 
 56 |   /**
 57 |    * Set state to a change
 58 |    * @param change
 59 |    * @returns succeeded or not
 60 |    */
 61 |   set(change: HTMLElement): boolean {
 62 |     const index = this.changes.indexOf(change);
 63 |     if (index === -1) {
 64 |       return false;
 65 |     } else {
 66 |       this.index = index;
 67 |       return true;
 68 |     }
 69 |   }
 70 | }
 71 | 
 72 | class UI_State {
 73 |   static readonly CSS_BORDER = "outline: 2px dashed #00F";
 74 | 
 75 |   private state: FocusState;
 76 |   private position_el: HTMLElement;
 77 | 
 78 |   /**
 79 |    * Create and initialize the UI state.
 80 |    *
 81 |    * `position` is the element showing position of the current change.
 82 |    */
 83 |   constructor(
 84 |     { changes, position }: { changes: HTMLElement[]; position: HTMLElement },
 85 |   ) {
 86 |     this.state = new FocusState(changes);
 87 | 
 88 |     this.position_el = position;
 89 |     this.update_position_text();
 90 |   }
 91 | 
 92 |   private update_position_text() {
 93 |     this.position_el.textContent = this.state.human_position();
 94 |   }
 95 | 
 96 |   jump_to(clicked_change: HTMLElement) {
 97 |     const last = this.state.current();
 98 |     const succeeded = this.state.set(clicked_change);
 99 |     if (succeeded) {
100 |       // Update texts and styles
101 |       this.clear_style(last);
102 |       this.set_style(clicked_change);
103 |       this.update_position_text();
104 |     }
105 |   }
106 | 
107 |   /** Scroll the current change into view */
108 |   private scroll_to(current: HTMLElement) {
109 |     // Update texts and styles
110 |     this.set_style(current);
111 |     this.update_position_text();
112 | 
113 |     // If `current` is in a ``, expand the ``
114 |     let parent = current.parentElement;
115 |     while (parent) {
116 |       if (parent.tagName.toLowerCase() === "details") {
117 |         (parent as HTMLDetailsElement).open = true;
118 |       }
119 |       parent = parent.parentElement;
120 |     }
121 | 
122 |     // Scroll `current` into view
123 |     const bCR = current.getBoundingClientRect();
124 |     const height = globalThis.innerHeight ||
125 |       document.documentElement.clientHeight;
126 |     if (
127 |       bCR.top < 0 || // we've scrolled past element
128 |       bCR.bottom > height // element is below the fold
129 |     ) {
130 |       current.scrollIntoView({ block: "center" });
131 |     }
132 |   }
133 | 
134 |   /** Clear the style of the current change */
135 |   private clear_style(current: HTMLElement | null) {
136 |     if (current) {
137 |       current.style.cssText = "";
138 |     }
139 |   }
140 |   /** Set the style of the current change */
141 |   private set_style(current: HTMLElement) {
142 |     current.style.cssText = UI_State.CSS_BORDER;
143 |   }
144 | 
145 |   to_next() {
146 |     this.clear_style(this.state.current());
147 |     this.scroll_to(this.state.next());
148 |   }
149 | 
150 |   to_previous() {
151 |     this.clear_style(this.state.current());
152 |     this.scroll_to(this.state.previous());
153 |   }
154 | 
155 |   stop() {
156 |     this.clear_style(this.state.current());
157 |     this.state.stop();
158 |     this.update_position_text();
159 |   }
160 | }
161 | 
162 | function create_elements(): {
163 |   next: HTMLDivElement;
164 |   previous: HTMLDivElement;
165 |   position: HTMLSpanElement;
166 | } {
167 |   const CSS_TEXT =
168 |     "float: left; padding: 5px 15px; border-left: 1px solid #999; cursor: pointer;";
169 | 
170 |   const container = document.createElement("div");
171 |   const display = document.createElement("div");
172 |   const previous = document.createElement("div");
173 |   const next = document.createElement("div");
174 |   const position = document.createElement("span");
175 | 
176 |   display.appendChild(position);
177 |   container.appendChild(display);
178 |   container.appendChild(previous);
179 |   container.appendChild(next);
180 |   document.body.appendChild(container);
181 | 
182 |   container.className = "w3c-htmldiff-nav";
183 |   container.style.cssText =
184 |     "background-image: linear-gradient(transparent,rgba(0,0,0,.05) 40%,rgba(0,0,0,.1)); font: 12px sans-serif; color: #666; border-top: 1px solid #999; border-right: 1px solid #999; border-left: 1px solid #999; position: fixed; bottom: 0; right: 25px; border-radius: 3px 3px 0 0; background-color: #eee; z-index: 2147483647;";
185 |   next.style.cssText = CSS_TEXT;
186 |   previous.style.cssText = CSS_TEXT;
187 |   display.style.cssText = "float: left; padding: 5px 5px;";
188 |   position.style.cssText =
189 |     "background-color: #fff; border: 1px solid #999; padding: 1px 5px; box-shadow: inset 0 1px 3px #ddd; border-radius: 2px";
190 |   next.textContent = "next ›";
191 |   next.title = 'Keyboard nav: use "j" to jump to next change.';
192 |   previous.textContent = "‹ previous";
193 |   previous.title = 'Keyboard nav: use "k" to jump to previous change.';
194 | 
195 |   return { next, previous, position };
196 | }
197 | 
198 | function init() {
199 |   const { next, previous, position } = create_elements();
200 | 
201 |   const selector = "del.diff-old, ins.diff-chg, ins.diff-new";
202 |   const changes = Array.from(document.querySelectorAll(selector))
203 |     .filter((e) =>
204 |       e.offsetWidth || e.offsetHeight || e.getClientRects().length
205 |     );
206 | 
207 |   const state = new UI_State({ changes, position });
208 | 
209 |   // Add mouse navigation
210 |   next.addEventListener("click", () => state.to_next());
211 |   previous.addEventListener("click", () => state.to_previous());
212 |   changes.forEach((el) =>
213 |     el.addEventListener("click", () => state.jump_to(el))
214 |   );
215 | 
216 |   // Add keyboard navigation
217 |   document.addEventListener("keydown", (e) => {
218 |     if (!e.metaKey && e.key === "j") {
219 |       state.to_next();
220 |     } else if (!e.metaKey && e.key === "k") {
221 |       state.to_previous();
222 |     } else if (!e.metaKey && (e.key === "Escape" || e.key === "Esc")) {
223 |       state.stop();
224 |     }
225 |   }, false);
226 | }
227 | 
228 | init();
229 | 


--------------------------------------------------------------------------------
/typ/templates/template.html:
--------------------------------------------------------------------------------
  1 | 
  2 | 
  3 |   
  4 |     
  5 |     
  6 |     
  7 |     
 12 |     
 16 |     clreq-gap for typst
 17 |     
 18 |     
 31 |   
 32 |   
 33 |     
 78 |     
 82 |       
111 |       
117 |         Go to repository
118 |         
119 |         
120 |           
125 |         
126 |       
127 |     
128 |     
129 |     © 2025-2025 typst-doc-cn. All rights reserved.
130 |   
131 | 
132 | 


--------------------------------------------------------------------------------
/typ/show-example.typ:
--------------------------------------------------------------------------------
  1 | #import "@preview/digestify:0.1.0": bytes-to-hex, md5
  2 | 
  3 | #import "templates/html-toolkit.typ": div-frame
  4 | #import "templates/html-fix.typ": external-svg
  5 | #import "mode.typ": cache-dir, cache-ready, mode
  6 | 
  7 | 
  8 | /// -> str
  9 | #let GENERAL-PREAMBLE = ```typ
 10 | #set text(
 11 |   lang: "zh", // required for localization
 12 |   font: ((name: "New Computer Modern", covers: "latin-in-cjk"), "Noto Serif CJK SC"),
 13 |   // Make it reproducible.
 14 |   fallback: false,
 15 | )
 16 | ```.text
 17 | 
 18 | 
 19 | /// Layout an example
 20 | ///
 21 | /// Edit from test cases of tidy.
 22 | /// https://github.com/Mc-Zen/tidy/blob/3dbdde92b1de56e516886255ce25ed813a87d008/tests/show-example/test.typ
 23 | ///
 24 | /// - code (content): a `raw` element containing the displayed code
 25 | /// - preview (content): previewed result
 26 | /// -> content
 27 | #let layout-example(code, preview) = html.div(
 28 |   class: "example",
 29 |   {
 30 |     code
 31 |     div-frame(preview, class: "preview")
 32 |   },
 33 | )
 34 | 
 35 | 
 36 | /// Layout an external example
 37 | ///
 38 | /// Drop the preview if the cache is not ready yet.
 39 | ///
 40 | /// - code (content): a `raw` element containing the displayed code
 41 | /// - id (str): ID of the executed code
 42 | /// -> content
 43 | #let layout-external-example(code, id) = {
 44 |   let path = cache-dir + "{id}.svg".replace("{id}", id)
 45 |   html.div(
 46 |     class: "example",
 47 |     // Put an annotation when hovering
 48 |     ..if mode == "dev" { (title: path) },
 49 |     {
 50 |       code
 51 |       html.div(class: "preview", if cache-ready {
 52 |         show image: external-svg
 53 |         image(path)
 54 |       })
 55 |     },
 56 |   )
 57 | }
 58 | 
 59 | 
 60 | /// `f: U → V`, `x: U | none` ⇒ `optional-map(f, x): V | none`
 61 | /// https://doc.rust-lang.org/stable/std/option/enum.Option.html#method.map
 62 | #let optional-map(f, x) = if x == none { none } else { f(x) }
 63 | 
 64 | /// - x (str):
 65 | /// -> str
 66 | #let hash(x) = bytes-to-hex(md5(bytes(x)))
 67 | 
 68 | 
 69 | /// Adds the language `example`, etc. to `raw` that can be used to render code examples side-by-side with an automatic preview.
 70 | ///
 71 | /// Please refer to https://github.com/Mc-Zen/tidy/releases/latest/download/tidy-guide.pdf#tidy-render-examples() for more info.
 72 | #let render-examples(
 73 |   /// Body to apply the show rule to.
 74 |   /// -> any
 75 |   body,
 76 | ) = {
 77 |   /// - raw (str): The source of a simple or page example.
 78 |   /// -> dictionary `(displayed, executed)`
 79 |   let parse-example(raw) = {
 80 |     let lines = raw
 81 |       .split("\n")
 82 |       .map(x => if x.starts-with(">>>") {
 83 |         (
 84 |           displayed: none,
 85 |           executed: x.trim(">>>", at: start),
 86 |         )
 87 |       } else if x.starts-with("<<<") {
 88 |         (
 89 |           displayed: if x == "<<<" {
 90 |             "" // Support displaying an empty line
 91 |           } else {
 92 |             // The space after `<<<` is intentional. It is consistent with the official, but different with tidy.
 93 |             assert(
 94 |               x.starts-with("<<< "),
 95 |               message: "this line in the example is ambiguous; consider adding a space after `<<<`:\n" + x,
 96 |             )
 97 |             x.trim("<<< ", at: start)
 98 |           },
 99 |           executed: none,
100 |         )
101 |       } else {
102 |         // Regular lines
103 |         (displayed: x, executed: x)
104 |       })
105 | 
106 | 
107 |     let displayed = lines.map(x => x.displayed).filter(x => x != none).join("\n")
108 |     let executed = lines.map(x => x.executed).filter(x => x != none).join("\n")
109 | 
110 |     (displayed: displayed, executed: executed)
111 |   }
112 | 
113 |   let fix-scaling(it) = {
114 |     // This reverts the default style for `raw`, making the result of `#context 1em.to-absolute()` in simple examples consistent with that in regular documents.
115 |     //
116 |     // We have to apply this to `layout*-example` functions in all kinds of examples.
117 |     //
118 |     // Reason: In typst v0.14.0-rc.1, `text.size` does not affect the apparent size of text in HTML, but does affect the conversion rate between the absolute lengths in Typst and HTML.
119 |     // If an image is sized absolutely in points, then typst will make sure its relative size to text is the same in both PNG/SVG/PDF and HTML.
120 |     // SVGs compiled from page and bibliography examples specify their sizes in absolute lengths.
121 |     // To make scales of preview images consistent, we have to apply this rule to all kinds of examples.
122 |     // https://github.com/typst/typst/issues/7114
123 |     set text(1em / 0.8)
124 | 
125 |     it
126 |   }
127 | 
128 |   // Simple example, directly evaluated in main.typ.
129 |   show raw.where(lang: "example"): it => {
130 |     let (displayed, executed) = parse-example(it.text)
131 | 
132 |     let full-executed = ````typ
133 |     // Some browsers hide the border. Therefore, the inset is necessary.
134 |     #show: block.with(inset: 0.5em)
135 |     {GENERAL-PREAMBLE}
136 | 
137 |     {executed}
138 |     ````
139 |       .text
140 |       .replace("{GENERAL-PREAMBLE}", GENERAL-PREAMBLE)
141 |       .replace("{executed}", executed)
142 | 
143 |     show: fix-scaling
144 |     layout-example(
145 |       optional-map(raw.with(block: true, lang: "typ"), displayed),
146 |       [#eval(full-executed, mode: "markup")],
147 |     )
148 |   }
149 | 
150 |   // Page example, compiled by scripts/compile.ts.
151 |   show raw.where(lang: "example-page"): it => {
152 |     let (displayed, executed) = parse-example(it.text)
153 | 
154 |     let full-executed = ````typ
155 |     // Some browsers hide the border. Therefore, the margin is necessary.
156 |     #set page(width: auto, height: auto, margin: 0.5em, fill: none)
157 |     {GENERAL-PREAMBLE}
158 | 
159 |     {executed}
160 |     ````
161 |       .text
162 |       .replace("{GENERAL-PREAMBLE}", GENERAL-PREAMBLE)
163 |       .replace("{executed}", executed)
164 | 
165 |     let id = "example-" + hash(full-executed)
166 |     [
167 |       #metadata((id: id, content: full-executed)) 
168 |     ]
169 |     show: fix-scaling
170 |     layout-external-example(optional-map(raw.with(block: true, lang: "typ"), displayed), id)
171 |   }
172 | 
173 |   // Bibliography example, compiled by scripts/compile.ts.
174 |   show raw.where(lang: "example-bib"): it => {
175 |     let lines = it.text.split("\n")
176 | 
177 |     let displayed = lines.filter(x => not x.starts-with("%")).join("\n")
178 |     let expected = lines.filter(x => x.starts-with("%")).map(x => x.trim("%", at: start).trim())
179 | 
180 |     let executed = ````typ
181 |     // Some browsers hide the border. Therefore, the margin is necessary.
182 |     #set page(width: 30em, height: auto, margin: 0.5em, fill: none)
183 |     {GENERAL-PREAMBLE}
184 | 
185 |     Current:
186 | 
187 |     #bibliography(
188 |       bytes(```{displayed}```.text),
189 |       style: "gb-7714-2015-numeric",
190 |       title: none,
191 |       full: true,
192 |     )
193 | 
194 |     Expected:
195 | 
196 |     #set enum(numbering: "[1]")
197 |     {expected}
198 |     ````
199 |       .text
200 |       .replace("{GENERAL-PREAMBLE}", GENERAL-PREAMBLE)
201 |       .replace("{displayed}", displayed)
202 |       .replace("{expected}", expected.map(x => "+ " + x).join("\n"))
203 | 
204 |     let id = "example-" + hash(executed)
205 |     [
206 |       #metadata((id: id, content: executed)) 
207 |     ]
208 |     show: fix-scaling
209 |     layout-external-example(raw(displayed, block: true, lang: "bib"), id)
210 |   }
211 | 
212 |   body
213 | }
214 | 
215 | /// Layout a git log in a ``
216 | #let layout-git-log(summary: [], log) = html.details(class: "example", {
217 |   html.summary(summary)
218 |   raw(log, lang: "gitlog", block: true)
219 | })
220 | 


--------------------------------------------------------------------------------
/scripts/generate-json-index.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Generate a JSON index and print to stdout.
  3 |  */
  4 | 
  5 | import assert from "node:assert";
  6 | import { fileURLToPath } from "node:url";
  7 | 
  8 | import type { IssueMeta, PullMeta } from "./check_issues.ts";
  9 | import { extraArgs } from "./config.ts";
 10 | import { typst } from "./typst.ts";
 11 | 
 12 | type Priority = "ok" | "advanced" | "basic" | "broken" | "tbd" | "na";
 13 | type GeneralPriority = Priority | "(inherited)";
 14 | 
 15 | // Parsed types
 16 | 
 17 | type Babel = { en: string; "zh-Hans": string };
 18 | 
 19 | type Heading = {
 20 |   level: number;
 21 |   body: Babel;
 22 |   label?: string;
 23 | };
 24 | type Section = {
 25 |   title: Babel;
 26 |   level: number;
 27 |   id?: string;
 28 |   priority: GeneralPriority;
 29 |   links: (
 30 |     | ({ type: "issue" } & IssueMeta)
 31 |     | ({ type: "pull" } & PullMeta)
 32 |     | ({ type: "workaround" } & WorkaroundMeta)
 33 |   )[];
 34 | };
 35 | 
 36 | // Typst elements
 37 | 
 38 | type HeadingElem = {
 39 |   func: "heading";
 40 |   level: number;
 41 |   body: ContentElem;
 42 |   label?: string;
 43 | };
 44 | type SpaceElem = { func: "space" };
 45 | type TextElem = { func: "text"; text: string };
 46 | type RawElem = { func: "raw"; text: string };
 47 | type Sequence = {
 48 |   func: "sequence";
 49 |   children: T[];
 50 | };
 51 | /** Same as `Sequence`, but without self-reference. */
 52 | type SequenceElem = {
 53 |   func: "sequence";
 54 |   children: ContentElem[];
 55 | };
 56 | type StyledElem = {
 57 |   func: "styled";
 58 |   child: ContentElem;
 59 |   styles: "..";
 60 | };
 61 | /**
 62 |  * The body of a heading element.
 63 |  *
 64 |  * Only relevant fields and combinations are included.
 65 |  */
 66 | type ContentElem =
 67 |   | StyledElem
 68 |   | SequenceElem
 69 |   | SpaceElem
 70 |   | TextElem
 71 |   | {
 72 |     func: "elem";
 73 |     tag: "span";
 74 |     attrs: { lang: "en" | "zh-Hans" } | { style: string };
 75 |     body: TextElem | Sequence;
 76 |   };
 77 | 
 78 | type WorkaroundMeta = {
 79 |   dest: string;
 80 |   note: string | null;
 81 | };
 82 | 
 83 | type GeneralMetadata =
 84 |   & { func: "metadata" }
 85 |   & (
 86 |     | { value: Priority; label: "" }
 87 |     | { value: IssueMeta; label: "" }
 88 |     | { value: PullMeta; label: "" }
 89 |     | { value: WorkaroundMeta; label: "" }
 90 |   );
 91 | 
 92 | function* _parseContent(
 93 |   it: ContentElem | RawElem | Sequence,
 94 | ): Generator<
 95 |   | { action: "pop"; text: string }
 96 |   | { action: "switch-lang"; next: "en" | "zh-Hans" }
 97 | > {
 98 |   const pop = (text: string) => ({ action: "pop" as const, text });
 99 |   const switchLang = (lang: "en" | "zh-Hans") => ({
100 |     action: "switch-lang" as const,
101 |     next: lang,
102 |   });
103 | 
104 |   switch (it.func) {
105 |     // Structural elements
106 |     case "sequence":
107 |       for (const child of it.children) {
108 |         yield* _parseContent(child);
109 |       }
110 |       break;
111 |     case "styled":
112 |       yield* _parseContent(it.child);
113 |       break;
114 | 
115 |     // Basic elements
116 |     case "text":
117 |       yield pop(it.text);
118 |       break;
119 |     case "space":
120 |       yield pop(" ");
121 |       break;
122 |     case "raw":
123 |       yield pop(`“${it.text}”`);
124 |       break;
125 | 
126 |     // HTML elements
127 |     case "elem":
128 |       if ("lang" in it.attrs) {
129 |         const lang = it.attrs.lang;
130 |         assert(
131 |           lang === "en" || lang === "zh-Hans",
132 |           `Invalid language: ${lang} in ${JSON.stringify(it)}`,
133 |         );
134 |         yield switchLang(lang);
135 |       }
136 |       yield* _parseContent(it.body);
137 |       break;
138 | 
139 |     default:
140 |       throw new Error(`Reached unexpected element: ${JSON.stringify(it)}`);
141 |   }
142 | }
143 | 
144 | function parseHeading(heading: HeadingElem): Heading {
145 |   const { level, body, label } = heading;
146 |   const parser = _parseContent(body);
147 | 
148 |   const parsed = { en: "", "zh-Hans": "" };
149 |   let lang: keyof typeof parsed = "en";
150 | 
151 |   for (const p of parser) {
152 |     switch (p.action) {
153 |       case "pop":
154 |         parsed[lang] += p.text;
155 |         break;
156 |       case "switch-lang":
157 |         // Remove the space added by `babel` between languages.
158 |         parsed[lang] = parsed[lang].trim();
159 |         lang = p.next;
160 |         break;
161 |       default:
162 |         throw new Error(`Invalid action: ${JSON.stringify(p)}`);
163 |     }
164 |   }
165 | 
166 |   // Fallback
167 |   parsed["zh-Hans"] ||= parsed.en;
168 |   parsed["en"] ||= parsed["zh-Hans"];
169 | 
170 |   return { level, body: parsed, label };
171 | }
172 | 
173 | function labelToId(label: string): string;
174 | function labelToId(label: undefined): undefined;
175 | function labelToId(label: string | undefined): string | undefined;
176 | function labelToId(label: string | undefined): string | undefined {
177 |   return label?.replace(/^<(.+)>$/, "$1");
178 | }
179 | 
180 | /** Get data by querying the typst document. */
181 | async function queryDocument(): Promise<(Heading | GeneralMetadata)[]> {
182 |   return (JSON.parse(
183 |     await typst([
184 |       "query",
185 |       "index.typ", // This cannot be main.typ, or there will be an additional heading (`outline`'s title).
186 |       [
187 |         "selector.or(heading, , , , )",
188 |         ".after(outline)",
189 |         ".before(, inclusive: false)",
190 |       ].join(""),
191 |       "--target=html",
192 |       ...extraArgs.pre,
193 |     ]),
194 |   ) as (HeadingElem | GeneralMetadata)[]).map((el) => {
195 |     if (el.func === "heading") {
196 |       return parseHeading(el);
197 |     }
198 |     return el;
199 |   });
200 | }
201 | 
202 | /** Collect data into sections. */
203 | function collectSections(data: (Heading | GeneralMetadata)[]): Section[] {
204 |   const sections: Section[] = [];
205 | 
206 |   for (const it of data) {
207 |     if ("level" in it) {
208 |       const { body: title, level, label } = it;
209 |       const id = labelToId(label);
210 |       sections.push({ id, title, level, priority: "(inherited)", links: [] });
211 |     } else {
212 |       const last = sections.at(-1);
213 |       assert(
214 |         last !== undefined,
215 |         `Metadata describe the heading before them, but there is no heading before this one: ${
216 |           JSON.stringify(it)
217 |         }`,
218 |       );
219 | 
220 |       switch (it.label) {
221 |         case "":
222 |           assert(
223 |             last.priority === "(inherited)",
224 |             `There are multiple priority levels marking the same section: heading = ${
225 |               JSON.stringify(last.title)
226 |             }, priority = [${last.priority}, ${it.value}, …]`,
227 |           );
228 |           last.priority = it.value;
229 |           break;
230 | 
231 |         case "":
232 |           last.links.push({ type: "issue", ...it.value });
233 |           break;
234 |         case "":
235 |           last.links.push({ type: "pull", ...it.value });
236 |           break;
237 |         case "":
238 |           last.links.push({ type: "workaround", ...it.value });
239 |           break;
240 | 
241 |         default:
242 |           throw new Error(`Reached unexpected element: ${JSON.stringify(it)}`);
243 |       }
244 |     }
245 |   }
246 |   return sections;
247 | }
248 | 
249 | /** Clean sections in place. */
250 | function cleanSections(sections: Section[]): void {
251 |   // Deduplicate links but keep the order.
252 |   // Links in `babel` might be duplicate, so this is necessary.
253 |   for (const section of sections) {
254 |     const seen = new Set();
255 |     section.links = section.links.filter((link) => {
256 |       const key = `${link.type}:${JSON.stringify(link)}`;
257 |       if (seen.has(key)) return false;
258 |       seen.add(key);
259 |       return true;
260 |     });
261 |   }
262 | }
263 | 
264 | /** Warn sections without `id` */
265 | function warnUnlabelledSections(sections: Section[]): void {
266 |   const unlabelled = sections.filter(({ id, priority }) =>
267 |     id === undefined && !["tbd", "na"].includes(priority)
268 |   );
269 | 
270 |   if (unlabelled.length > 0) {
271 |     console.warn(
272 |       `Found ${unlabelled.length} unlabelled sections:\n${
273 |         unlabelled.map(({ title, level, priority }) =>
274 |           `${"  ".repeat(level)}- ${
275 |             priority === "(inherited)" ? "" : `[${priority}] `
276 |           }${title.en} | ${title["zh-Hans"]}`
277 |         ).join("\n")
278 |       }`,
279 |     );
280 |   }
281 | }
282 | 
283 | if (process.argv[1] === fileURLToPath(import.meta.url)) {
284 |   const data = await queryDocument();
285 |   const sections = collectSections(data);
286 |   cleanSections(sections);
287 | 
288 |   console.log(JSON.stringify({ version: "2025-11-24", sections }, null, 2));
289 | 
290 |   warnUnlabelledSections(sections);
291 | }
292 | 


--------------------------------------------------------------------------------
/README.en.md:
--------------------------------------------------------------------------------
  1 | # [clreq](https://www.w3.org/TR/clreq/)-[gap](https://www.w3.org/TR/clreq-gap/) for [typst](https://typst.app/home)
  2 | 
  3 | Chinese Layout Gap Analysis for Typst.
  4 | 分析 Typst 与中文排版的差距。
  5 | 
  6 | [![Check](https://github.com/typst-doc-cn/clreq/actions/workflows/check.yml/badge.svg)](https://github.com/typst-doc-cn/clreq/actions/workflows/check.yml)
  7 | [![Website](https://img.shields.io/website?url=https%3A%2F%2Ftypst-doc-cn.github.io%2Fclreq%2F&label=Website)](https://typst-doc-cn.github.io/clreq/)
  8 | 
  9 | **Languages: [English (current)](./README.en.md)** | **[中文](./README.md)**
 10 | 
 11 | 
 12 | Typst is a markup-based typesetting software, and this document describes gaps or shortcomings for the support of the Chinese script within Typst.
 13 | In particular, it is concerned with [text layout](https://www.w3.org/TR/clreq/) and [bibliography](https://std.samr.gov.cn/gb/search/gbDetailed?id=71F772D8055ED3A7E05397BE0A0AB82A).
 14 | It examines whether needed features are supported by the typst compiler, and provides information on potential workarounds.
 15 | 
 16 | 
 17 | [The main the document is on the website](https://typst-doc-cn.github.io/clreq/), and the following is the contributing guide.
 18 | 
 19 | ## Contributing Guide
 20 | 
 21 | ### Feedback
 22 | 
 23 | If you find anything missing or incorrect, or have any questions or suggestions, please raise them on [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/).
 24 | 
 25 | - Language: Both Chinese and English are acceptable here. When it’s ready, we will forward it to [the Typst official](https://github.com/typst/typst/) in English, and complete both translations in this document.
 26 | 
 27 | - If it is your first time, you can refer to [W3C’s guide on GitHub Issue (with screenshots, in English)](https://www.w3.org/International/i18n-activity/guidelines/issues.html).
 28 | 
 29 | ### Edit the document
 30 | 
 31 | The main document is generated by Typst. For daily edits:
 32 | 
 33 | 1. [Open `main.typ` on GitHub](https://github.com/typst-doc-cn/clreq/blob/main/main.typ)
 34 | 2. Click the edit button `✏️` on the top right corner, and follow the prompts to get ready (log in, fork, etc.).
 35 | 3. Edit `main.typ`.
 36 | 4. Click _Commit changes…_ on the top right corner, and follow the prompts to complete the editing (briefly explain it, create a pull request, etc.).
 37 | 5. Wait a moment, and robots will render the new version as a web page and comment it under the pull request. You can continue editing if necessary.
 38 | 
 39 | 
 40 | To preview it locally
 41 | 
 42 | ```shell
 43 | # Compile
 44 | pnpm build # ⇒ dist/index.html
 45 | 
 46 | # Recompile on changes
 47 | pnpm dev --open # ⇒ http://localhost:3000
 48 | ```
 49 | 
 50 | Prerequisites:
 51 | 
 52 | - [pnpm](https://pnpm.io), the package manager
 53 | 
 54 | - _Noto Serif CJK SC_, the typeface
 55 | 
 56 |   1. Download [`09_NotoSerifCJKsc.zip`](https://mirrors.cernet.edu.cn/github-release/googlefonts/noto-cjk/LatestRelease/09_NotoSerifCJKsc.zip) from [校园网联合镜像站 · Google Fonts](https://mirrors.cernet.edu.cn/font/GoogleFonts), or [Language Specific OTFs Simplified Chinese (简体中文)](https://github.com/notofonts/noto-cjk/releases/latest/download/09_NotoSerifCJKsc.zip) from [GitHub Releases · notofonts/noto-cjk](https://github.com/notofonts/noto-cjk/releases).
 57 | 
 58 |   2. Then install the fonts to system, or put them under `./fonts/`.
 59 | 
 60 |   _Noto Serif CJK SC_ is enough for most contributors. However, if you want to reproduce all examples exactly, please refer to [`download_fonts.sh`](./scripts/download_fonts.sh).
 61 | 
 62 | 
 63 | 
 64 | ## Reference for writing `main.typ`
 65 | 
 66 | ### Content scope
 67 | 
 68 | For each issue, please try to:
 69 | 
 70 | - Briefly describe the problem
 71 | 
 72 | - Provide a concise example that can be understood at a glance
 73 | 
 74 | - Supplement the background that those who do not understand Chinese may not be clear about
 75 | 
 76 |   For example, typing Chinese characters requires an IME. You can link to [Unicode FAQ on Chinese and Japanese](https://unicode.org/faq/han_cjk.html).
 77 | 
 78 | But in most cases:
 79 | 
 80 | - No need to provide a solution directly
 81 | 
 82 |   Just link it as `#workaround("https://…")`.
 83 | 
 84 | - No need to describe comprehensively, nor is it recommended to propose improvements too much
 85 | 
 86 |   These contents can be initially proposed at [GitHub Issues](https://github.com/typst-doc-cn/clreq/issues/), and should eventually be forwarded to the Typst official.
 87 | 
 88 | ### Maintaining
 89 | 
 90 | GitHub Actions are watching `#issue` and `#pull` annotated in the document, and will report in [🤖 Cron check · Issue #22](https://github.com/typst-doc-cn/clreq/issues/22) and pull request if their states change.
 91 | 
 92 | We can update the document once we notice. There is no need to wait until Typst releases a new version.
 93 | 
 94 | An example update is as below.
 95 | 
 96 | ```diff
 97 | - #level.basic
 98 | + #level.ok
 99 | - #issue("typst#633")
100 | - #pull("typst#5777")
101 | + #issue("typst#633", closed: true)
102 | + #pull("typst#5777", merged: true)
103 |   #workaround("https://typst-doc-cn.github.io/guide/FAQ/cite-flying.html")
104 | +
105 | + #till-next(now-fixed.with(last-affected: "0.13.1", last-level: "basic"))
106 | ```
107 | 
108 | ### Multilingual content (`babel`/`bbl`)
109 | 
110 | - The `en` and `zh` fields are displayed in English and 中文 modes, respectively.
111 | 
112 | - `babel` is used for paragraphs `par`, and generates block-level elements (``); while `bbl` is used for short phrases within paragraphs, and generates inline elements (``).
113 | 
114 | Example:
115 | 
116 | ```typst
117 | === #bbl(en: [Vertical Writing Mode], zh: [直排])
118 | 
119 | #babel(
120 |   en: [There are *two* writing modes in Chinese composition…],
121 |   zh: [中文有*两种*行文模式……],
122 | )
123 | ```
124 | 
125 | Tips:
126 | 
127 | - When drafting a pull request, there is no need to write a full bilingual translation at the very beginning. You can start with a single language and then add others after the content is finalized.
128 | 
129 | - Not all content needs to be translated. Some terms are not possible to be translated, or might be ambiguous when only read in a single language. In such cases, there is no need to wrap `bbl`; just write them directly.
130 | 
131 | - Don’t pay special attention to line breaks and indentation. Just use tinymist (VS Code) / typstyle default settings. To make version comparison easier, we have set up a pull request robot to automatically format them.
132 | 
133 | ### Title formats
134 | 
135 | - Top-level sections representing **categories**
136 | 
137 |   The title should be as consistent as possible with [W3C Gap Analysis documents](https://www.w3.org/TR/clreq-gap/).
138 | 
139 | - Low-level sections derscribing **specific gaps**
140 | 
141 |   - For features that are needed but **not yet supported**, express titles as **phrases** whenever possible.
142 | 
143 |     Examples:
144 | 
145 |     - Vertical writing mode | 直排
146 |     - Customizing punctuation overhang | 定制标点悬挂
147 | 
148 |   - For issues of **existing** features, express titles as **sentences** whenever possible.
149 | 
150 |     Examples:
151 | 
152 |     - Spacing between heading numbering and title is too wide | 标题编号与内容之间的空隙过宽
153 |     - Citation numbers are flying over their brackets | 引用编号的数字高于括号
154 | 
155 |   - Do not edit the title after the gap is resolved, unless you have a good reason.
156 | 
157 | ### Adding a code example
158 | 
159 | Code examples will be compiled when rendering the website.
160 | 
161 | When writing code examples:
162 | 
163 | - Ensure that it is independent of the display language. `babel` is not supported and should not be used
164 | 
165 | - Use Han characters for placeholders if possible. Add punctuations and Latin letters only when necessary
166 | 
167 | - Try to avoid including descriptive text in the code. If really unavoidable, choose English phrases or emojis when possible
168 | 
169 | To add an example, insert a fenced code block with one of the following languages. We will introduce them one by one.
170 | 
171 | #### Simple examples (`example`)
172 | 
173 | A simple typst example.
174 | 
175 | ````typst
176 | ```example
177 | >>> Current: \
178 | #underline[中文和English]
179 | 
180 | >>> Expected: \
181 | >>> #set underline(offset: .15em, stroke: .05em)
182 | >>> #underline[中文和English]
183 | ```
184 | ````
185 | 
186 | - Regular lines:
187 | 
188 |   👀 shown as the source, and 🚀 executed in preview.
189 | 
190 | - Lines starting with `>>>`:
191 | 
192 |   🙈 hidden from the source, but still 🚀 executed in preview.
193 | 
194 | - Lines starting with `<<< `:
195 | 
196 |   👀 shown as the source, but 🛑 not executed in the preview.
197 | 
198 | ##### Limitations and caveats
199 | 
200 | Simple examples are evaluated in a container and their states are shared across the entire document.
201 | 
202 | As a result:
203 | 
204 | - Any page configuration is not allowed.
205 | 
206 |   If you just want to `#set page(width: …)`, then use `#show: block.with(width: …)` instead.
207 | 
208 | - Updating counters will affect the following examples.
209 | 
210 | - Citations and bibliographies will conflict with other examples.
211 | 
212 | - The default configuration values are those specified in `raw`, which may differ from the defaults in regular documents.
213 | 
214 |   For example, the default `text.cjk-latin-spacing` is typically `auto`, but here it is `none`.
215 | 
216 | - The styles for headings etc. are affected by the global style of the document.
217 | 
218 | - …
219 | 
220 | If you require advanced features or 100% accuracy, please write a page example instead.
221 | 
222 | #### Page examples (`example-page`)
223 | 
224 | A standalone typst example compiled in a page.
225 | 
226 | `````typst
227 | ````example-page
228 | >>> Current: \
229 | 孔乙己@key
230 | 
231 | >>> Expected: \
232 | >>> 孔乙己@key
233 | >>> #show bibliography: none
234 | #let bib = ```bib
235 | @misc{key,
236 |   title = {Title},
237 | }
238 | ```.text
239 | #bibliography(bytes(bib), style: "gb-7714-2015-numeric")
240 | ````
241 | `````
242 | 
243 | The meanings of `<<< ` and `>>>` are the same as those in simple examples.
244 | 
245 | #### Bibliography examples (`example-bib`)
246 | 
247 | ````typst
248 | ```example-bib
249 | @book{key,
250 |   title = {标题},
251 |   author = {作者},
252 |   year = {2025}
253 | }
254 | % 作者. 标题. 2025.
255 | ```
256 | ````
257 | 
258 | - Regular lines: BibTeX entries.
259 | 
260 | - Lines starting with `%`: Expected output.
261 | 
262 | ## License
263 | 
264 | The code are licensed under Apache 2.0 unless otherwise specified. All rights of rest content are reserved.
265 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
  1 |                                  Apache License
  2 |                            Version 2.0, January 2004
  3 |                         http://www.apache.org/licenses/
  4 | 
  5 |    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
  6 | 
  7 |    1. Definitions.
  8 | 
  9 |       "License" shall mean the terms and conditions for use, reproduction,
 10 |       and distribution as defined by Sections 1 through 9 of this document.
 11 | 
 12 |       "Licensor" shall mean the copyright owner or entity authorized by
 13 |       the copyright owner that is granting the License.
 14 | 
 15 |       "Legal Entity" shall mean the union of the acting entity and all
 16 |       other entities that control, are controlled by, or are under common
 17 |       control with that entity. For the purposes of this definition,
 18 |       "control" means (i) the power, direct or indirect, to cause the
 19 |       direction or management of such entity, whether by contract or
 20 |       otherwise, or (ii) ownership of fifty percent (50%) or more of the
 21 |       outstanding shares, or (iii) beneficial ownership of such entity.
 22 | 
 23 |       "You" (or "Your") shall mean an individual or Legal Entity
 24 |       exercising permissions granted by this License.
 25 | 
 26 |       "Source" form shall mean the preferred form for making modifications,
 27 |       including but not limited to software source code, documentation
 28 |       source, and configuration files.
 29 | 
 30 |       "Object" form shall mean any form resulting from mechanical
 31 |       transformation or translation of a Source form, including but
 32 |       not limited to compiled object code, generated documentation,
 33 |       and conversions to other media types.
 34 | 
 35 |       "Work" shall mean the work of authorship, whether in Source or
 36 |       Object form, made available under the License, as indicated by a
 37 |       copyright notice that is included in or attached to the work
 38 |       (an example is provided in the Appendix below).
 39 | 
 40 |       "Derivative Works" shall mean any work, whether in Source or Object
 41 |       form, that is based on (or derived from) the Work and for which the
 42 |       editorial revisions, annotations, elaborations, or other modifications
 43 |       represent, as a whole, an original work of authorship. For the purposes
 44 |       of this License, Derivative Works shall not include works that remain
 45 |       separable from, or merely link (or bind by name) to the interfaces of,
 46 |       the Work and Derivative Works thereof.
 47 | 
 48 |       "Contribution" shall mean any work of authorship, including
 49 |       the original version of the Work and any modifications or additions
 50 |       to that Work or Derivative Works thereof, that is intentionally
 51 |       submitted to Licensor for inclusion in the Work by the copyright owner
 52 |       or by an individual or Legal Entity authorized to submit on behalf of
 53 |       the copyright owner. For the purposes of this definition, "submitted"
 54 |       means any form of electronic, verbal, or written communication sent
 55 |       to the Licensor or its representatives, including but not limited to
 56 |       communication on electronic mailing lists, source code control systems,
 57 |       and issue tracking systems that are managed by, or on behalf of, the
 58 |       Licensor for the purpose of discussing and improving the Work, but
 59 |       excluding communication that is conspicuously marked or otherwise
 60 |       designated in writing by the copyright owner as "Not a Contribution."
 61 | 
 62 |       "Contributor" shall mean Licensor and any individual or Legal Entity
 63 |       on behalf of whom a Contribution has been received by Licensor and
 64 |       subsequently incorporated within the Work.
 65 | 
 66 |    2. Grant of Copyright License. Subject to the terms and conditions of
 67 |       this License, each Contributor hereby grants to You a perpetual,
 68 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 69 |       copyright license to reproduce, prepare Derivative Works of,
 70 |       publicly display, publicly perform, sublicense, and distribute the
 71 |       Work and such Derivative Works in Source or Object form.
 72 | 
 73 |    3. Grant of Patent License. Subject to the terms and conditions of
 74 |       this License, each Contributor hereby grants to You a perpetual,
 75 |       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
 76 |       (except as stated in this section) patent license to make, have made,
 77 |       use, offer to sell, sell, import, and otherwise transfer the Work,
 78 |       where such license applies only to those patent claims licensable
 79 |       by such Contributor that are necessarily infringed by their
 80 |       Contribution(s) alone or by combination of their Contribution(s)
 81 |       with the Work to which such Contribution(s) was submitted. If You
 82 |       institute patent litigation against any entity (including a
 83 |       cross-claim or counterclaim in a lawsuit) alleging that the Work
 84 |       or a Contribution incorporated within the Work constitutes direct
 85 |       or contributory patent infringement, then any patent licenses
 86 |       granted to You under this License for that Work shall terminate
 87 |       as of the date such litigation is filed.
 88 | 
 89 |    4. Redistribution. You may reproduce and distribute copies of the
 90 |       Work or Derivative Works thereof in any medium, with or without
 91 |       modifications, and in Source or Object form, provided that You
 92 |       meet the following conditions:
 93 | 
 94 |       (a) You must give any other recipients of the Work or
 95 |           Derivative Works a copy of this License; and
 96 | 
 97 |       (b) You must cause any modified files to carry prominent notices
 98 |           stating that You changed the files; and
 99 | 
100 |       (c) You must retain, in the Source form of any Derivative Works
101 |           that You distribute, all copyright, patent, trademark, and
102 |           attribution notices from the Source form of the Work,
103 |           excluding those notices that do not pertain to any part of
104 |           the Derivative Works; and
105 | 
106 |       (d) If the Work includes a "NOTICE" text file as part of its
107 |           distribution, then any Derivative Works that You distribute must
108 |           include a readable copy of the attribution notices contained
109 |           within such NOTICE file, excluding those notices that do not
110 |           pertain to any part of the Derivative Works, in at least one
111 |           of the following places: within a NOTICE text file distributed
112 |           as part of the Derivative Works; within the Source form or
113 |           documentation, if provided along with the Derivative Works; or,
114 |           within a display generated by the Derivative Works, if and
115 |           wherever such third-party notices normally appear. The contents
116 |           of the NOTICE file are for informational purposes only and
117 |           do not modify the License. You may add Your own attribution
118 |           notices within Derivative Works that You distribute, alongside
119 |           or as an addendum to the NOTICE text from the Work, provided
120 |           that such additional attribution notices cannot be construed
121 |           as modifying the License.
122 | 
123 |       You may add Your own copyright statement to Your modifications and
124 |       may provide additional or different license terms and conditions
125 |       for use, reproduction, or distribution of Your modifications, or
126 |       for any such Derivative Works as a whole, provided Your use,
127 |       reproduction, and distribution of the Work otherwise complies with
128 |       the conditions stated in this License.
129 | 
130 |    5. Submission of Contributions. Unless You explicitly state otherwise,
131 |       any Contribution intentionally submitted for inclusion in the Work
132 |       by You to the Licensor shall be under the terms and conditions of
133 |       this License, without any additional terms or conditions.
134 |       Notwithstanding the above, nothing herein shall supersede or modify
135 |       the terms of any separate license agreement you may have executed
136 |       with Licensor regarding such Contributions.
137 | 
138 |    6. Trademarks. This License does not grant permission to use the trade
139 |       names, trademarks, service marks, or product names of the Licensor,
140 |       except as required for reasonable and customary use in describing the
141 |       origin of the Work and reproducing the content of the NOTICE file.
142 | 
143 |    7. Disclaimer of Warranty. Unless required by applicable law or
144 |       agreed to in writing, Licensor provides the Work (and each
145 |       Contributor provides its Contributions) on an "AS IS" BASIS,
146 |       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 |       implied, including, without limitation, any warranties or conditions
148 |       of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 |       PARTICULAR PURPOSE. You are solely responsible for determining the
150 |       appropriateness of using or redistributing the Work and assume any
151 |       risks associated with Your exercise of permissions under this License.
152 | 
153 |    8. Limitation of Liability. In no event and under no legal theory,
154 |       whether in tort (including negligence), contract, or otherwise,
155 |       unless required by applicable law (such as deliberate and grossly
156 |       negligent acts) or agreed to in writing, shall any Contributor be
157 |       liable to You for damages, including any direct, indirect, special,
158 |       incidental, or consequential damages of any character arising as a
159 |       result of this License or out of the use or inability to use the
160 |       Work (including but not limited to damages for loss of goodwill,
161 |       work stoppage, computer failure or malfunction, or any and all
162 |       other commercial damages or losses), even if such Contributor
163 |       has been advised of the possibility of such damages.
164 | 
165 |    9. Accepting Warranty or Additional Liability. While redistributing
166 |       the Work or Derivative Works thereof, You may choose to offer,
167 |       and charge a fee for, acceptance of support, warranty, indemnity,
168 |       or other liability obligations and/or rights consistent with this
169 |       License. However, in accepting such obligations, You may act only
170 |       on Your own behalf and on Your sole responsibility, not on behalf
171 |       of any other Contributor, and only if You agree to indemnify,
172 |       defend, and hold each Contributor harmless for any liability
173 |       incurred by, or claims asserted against, such Contributor by reason
174 |       of your accepting any such warranty or additional liability.
175 | 
176 |    END OF TERMS AND CONDITIONS
177 | 
178 |    APPENDIX: How to apply the Apache License to your work.
179 | 
180 |       To apply the Apache License to your work, attach the following
181 |       boilerplate notice, with the fields enclosed by brackets "[]"
182 |       replaced with your own identifying information. (Don't include
183 |       the brackets!)  The text should be enclosed in the appropriate
184 |       comment syntax for the file format. We also recommend that a
185 |       file or class name and description of purpose be included on the
186 |       same "printed page" as the copyright notice for easier
187 |       identification within third-party archives.
188 | 
189 |    Copyright [yyyy] [name of copyright owner]
190 | 
191 |    Licensed under the Apache License, Version 2.0 (the "License");
192 |    you may not use this file except in compliance with the License.
193 |    You may obtain a copy of the License at
194 | 
195 |        http://www.apache.org/licenses/LICENSE-2.0
196 | 
197 |    Unless required by applicable law or agreed to in writing, software
198 |    distributed under the License is distributed on an "AS IS" BASIS,
199 |    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 |    See the License for the specific language governing permissions and
201 |    limitations under the License.
202 | 


--------------------------------------------------------------------------------
/src/respec/structure.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Handles producing the ToC, numbering sections, and permalinks across the document.
  3 |  *
  4 |  * Adapted from ReSpec.
  5 |  *
  6 |  * https://github.com/speced/respec/blob/eaa1596ef5c4207ab350808c1593d3a39600fbed/src/core/structure.js
  7 |  * https://github.com/speced/respec/blob/eaa1596ef5c4207ab350808c1593d3a39600fbed/src/core/id-headers.js
  8 |  * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document
  9 |  *
 10 |  * @module
 11 |  */
 12 | 
 13 | import { addId, html, renameElement } from "./utils.ts";
 14 | 
 15 | interface Section {
 16 |   header: HTMLElement;
 17 |   title: string;
 18 |   subsections: Section[];
 19 | }
 20 | 
 21 | /**
 22 |  * Scans sections and generate ordered list element + ID-to-anchor-content dictionary.
 23 |  * @param sections the target element to find child sections
 24 |  */
 25 | function scanSections(
 26 |   sections: Section[],
 27 |   maxTocLevel: number,
 28 |   { level = 1 } = {},
 29 | ): HTMLElement | null {
 30 |   if (sections.length === 0) {
 31 |     return null;
 32 |   }
 33 | 
 34 |   // @ts-ignore
 35 |   const ol = html`
 36 |     

 37 |   ` as HTMLElement;
 38 |   for (const section of sections) {
 39 |     if (level <= maxTocLevel) {
 40 |       const id = section.header.id;
 41 |       const item = createTocListItem(section.header, id);
 42 |       const sub = scanSections(section.subsections, maxTocLevel, {
 43 |         level: level + 1,
 44 |       });
 45 |       if (sub) {
 46 |         item.append(sub);
 47 |       }
 48 |       ol.append(item);
 49 |     }
 50 |   }
 51 |   return ol;
 52 | }
 53 | 
 54 | function getSectionTree(parent: Element): Section[] {
 55 |   const headings = parent.querySelectorAll("h2, h3, h4, h5, h6");
 56 |   const sections: Section[] = [];
 57 | 
 58 |   /**
 59 |    * A map from section levels to the last section encountered at the level.
 60 |    *
 61 |    * The level is counting from 2.
 62 |    */
 63 |   const lastSectionAtLevel = new Map();
 64 | 
 65 |   for (const heading of headings) {
 66 |     const level = parseInt(heading.tagName[1], 10);
 67 |     const title = heading.textContent as string;
 68 |     addId(heading, null, title);
 69 | 
 70 |     const section: Section = {
 71 |       header: heading,
 72 |       title,
 73 |       subsections: [],
 74 |     };
 75 | 
 76 |     const parent = lastSectionAtLevel.get(level - 1);
 77 |     if (level === 2 || parent === undefined) {
 78 |       // This is the top level
 79 |       sections.push(section);
 80 |     } else {
 81 |       parent.subsections.push(section);
 82 |     }
 83 | 
 84 |     // Update the cache
 85 |     lastSectionAtLevel.set(level, section);
 86 |     // Clear below this level
 87 |     for (let i = level + 1; i <= 6; i++) {
 88 |       lastSectionAtLevel.delete(i);
 89 |     }
 90 |   }
 91 | 
 92 |   return sections;
 93 | }
 94 | 
 95 | function createTocListItem(header: Element, id: string): HTMLElement {
 96 |   const anchor = html`
 97 |     
 98 |   ` as HTMLElement;
 99 |   anchor.append(...header.cloneNode(true).childNodes);
100 |   filterHeader(anchor);
101 |   return html`
102 |     ${anchor}
103 |   ` as HTMLElement;
104 | }
105 | 
106 | /**
107 |  * Replaces any child  and  with .
108 |  */
109 | function filterHeader(h: HTMLElement): void {
110 |   h.querySelectorAll("a").forEach((anchor) => {
111 |     const span = renameElement(anchor, "span");
112 |     span.className = "formerLink";
113 |     span.removeAttribute("href");
114 |   });
115 |   h.querySelectorAll("dfn").forEach((dfn) => {
116 |     const span = renameElement(dfn, "span");
117 |     span.removeAttribute("id");
118 |   });
119 | }
120 | 
121 | function createTableOfContents(ol: HTMLElement): HTMLElement {
122 |   const nav = html`
123 |     
124 |   ` as HTMLElement;
125 |   const h2 = html`
126 |     
127 |       Contents
128 |       目录
129 |     
130 |   `;
131 |   nav.append(h2, ol);
132 |   const ref = document.getElementById("toc") ??
133 |     document.getElementById("sotd") ??
134 |     document.getElementById("abstract");
135 |   if (ref) {
136 |     if (ref.id === "toc") {
137 |       ref.replaceWith(nav);
138 |     } else {
139 |       ref.after(nav);
140 |     }
141 |   }
142 | 
143 |   return nav;
144 | }
145 | 
146 | /** Add permalinks to headings */
147 | function addPermalinks(): void {
148 |   const headings = document.querySelectorAll("h2, h3, h4, h5, h6");
149 |   for (const h of headings) {
150 |     if (h.id) {
151 |       const permalink = html`
152 |         
159 |       `;
160 |       h.prepend(permalink);
161 |     }
162 |   }
163 | }
164 | 
165 | interface PriorityLevel {
166 |   paint: string;
167 |   human: string;
168 | }
169 | type LevelName = "tbd" | "na" | "ok" | "advanced" | "basic" | "broken";
170 | 
171 | /**
172 |  * Configuration of levels, sorted.
173 |  */
174 | const PRIORITY_CONFIG: Record = {
175 |   tbd: { paint: "eeeeee", human: "To be done" },
176 |   na: { paint: "008000", human: "Not applicable" },
177 |   ok: { paint: "008000", human: "OK" },
178 |   advanced: { paint: "ffe4b5", human: "Advanced" },
179 |   basic: { paint: "ffa500", human: "Basic" },
180 |   broken: { paint: "ff0000", human: "Broken" },
181 | };
182 | 
183 | /**
184 |  * Collect all priority levels in `element`.
185 |  */
186 | function collectPriorityLevels(elements: HTMLElement[]): LevelName[] {
187 |   return elements.flatMap((el) => {
188 |     const tags = Array.from(
189 |       el.querySelectorAll("[data-priority-level]"),
190 |     );
191 |     return tags.map((t) => t.dataset.priorityLevel as LevelName);
192 |   });
193 | }
194 | 
195 | /**
196 |  * Calculate statistics of priority levels
197 |  *
198 |  * The returned `counts` will sorted from the most important to the least important according to `PRIORITY_CONFIG`.
199 |  * If `levels` is empty, return `null`
200 |  */
201 | function countPriorityLevels(
202 |   levels: LevelName[],
203 | ): { worst: PriorityLevel; report: string } | null {
204 |   if (levels.length === 0) {
205 |     return null;
206 |   }
207 | 
208 |   // Calculate `worst` and `report`
209 |   const ordering = Object.keys(PRIORITY_CONFIG) as LevelName[];
210 |   const worst = PRIORITY_CONFIG[
211 |     ordering[
212 |       Math.max(...levels.map((l) => ordering.indexOf(l)))
213 |     ]
214 |   ];
215 | 
216 |   const counts: Map = levels.reduce(
217 |     (last, l) => last.set(l, (last.get(l) as number) + 1),
218 |     new Map(ordering.reverse().map((l) => [l, 0])),
219 |   );
220 |   const report = Array.from(counts.entries()).filter(([_level, n]) => n > 0)
221 |     .map(([level, n]) => `${n} ${PRIORITY_CONFIG[level].human}`).join(", ");
222 | 
223 |   return { worst, report };
224 | }
225 | 
226 | /**
227 |  * Calculate priority levels for all sections, and insert levels in them
228 |  * @param sections The section tree
229 |  * @returns Top sections’ levels if this is the top level
230 |  */
231 | function insertPriorityLevel(
232 |   sections: Section[],
233 |   siblings: HTMLElement[] | null = null,
234 | ): Map | undefined {
235 |   if (sections.length === 0) {
236 |     return;
237 |   }
238 | 
239 |   /** Whether the current iteration is the top level */
240 |   const isTop = siblings === null;
241 | 
242 |   // If not given, fill with the default
243 |   if (siblings === null) {
244 |     const parent = sections[0].header.parentElement as HTMLElement;
245 |     console.assert(
246 |       sections.every((s) => s.header.parentElement === parent),
247 |       "All subsections under the same section should have the same parent element",
248 |     );
249 |     siblings = Array.from(parent.children) as HTMLElement[];
250 |   }
251 | 
252 |   /** The start index of each section */
253 |   const startIndices = sections.map((s) => siblings.indexOf(s.header));
254 |   console.assert(
255 |     startIndices.every((i) => i !== -1),
256 |     "failed to one or more sections in siblings",
257 |     sections.filter((s) => siblings.indexOf(s.header) === -1),
258 |     siblings,
259 |   );
260 | 
261 |   const topSectionLevels = new Map();
262 | 
263 |   // Insert levels recursively, and save `topSectionLevels`
264 |   sections.forEach((sec, i) => {
265 |     const start = startIndices[i];
266 |     const end = startIndices.at(i + 1);
267 | 
268 |     const levels = collectPriorityLevels(siblings.slice(start, end));
269 | 
270 |     // if leaf section
271 |     if (sec.subsections.length === 0) {
272 |       console.assert(
273 |         levels.length <= 1,
274 |         `at most one priority level could be annotated in leaf sections, but found ${levels}: ${sec.title}`,
275 |         sec,
276 |       );
277 |     } else if (levels.length > 0) {
278 |       if (isTop) {
279 |         topSectionLevels.set(sec.header, levels);
280 |       }
281 | 
282 |       const { worst, report } = countPriorityLevels(levels)!;
283 | 
284 |       // Find the first non prompt element
285 |       let pos = sec.header;
286 |       while (
287 |         pos.nextElementSibling !== null &&
288 |         pos.nextElementSibling.classList.contains("prompt")
289 |       ) {
290 |         pos = pos.nextElementSibling as HTMLElement;
291 |       }
292 | 
293 |       // Write levels after `pos`
294 |       const p = html`
295 |         
296 |           
300 |           ${worst.human} — ${report}.
301 |         
302 |       ` as HTMLElement;
303 |       pos.insertAdjacentElement("afterend", p);
304 | 
305 |       // Insert recursively
306 |       insertPriorityLevel(sec.subsections, siblings.slice(start, end));
307 |     }
308 |   });
309 | 
310 |   if (topSectionLevels.size > 0) {
311 |     return topSectionLevels;
312 |   }
313 | }
314 | 
315 | /**
316 |  * Draw top sections’ levels at `ol#summary`.
317 |  */
318 | function createSummary(
319 |   topSectionLevels: Map,
320 | ): void {
321 |   // return
322 |   const ol = document.querySelector("ol#summary")!;
323 | 
324 |   for (const [sec, levels] of topSectionLevels) {
325 |     console.assert(levels.length > 0);
326 | 
327 |     // Draw dots
328 |     const ordering = Object.keys(PRIORITY_CONFIG) as LevelName[];
329 |     const sortedLevels = [...levels].sort((a, b) => {
330 |       return ordering.indexOf(b) - ordering.indexOf(a);
331 |     });
332 | 
333 |     const dots = html`
334 |       
335 |     `;
336 |     sortedLevels.forEach((level) => {
337 |       const { paint } = PRIORITY_CONFIG[level];
338 |       const dot = html`
339 |         
340 |       ` as HTMLElement;
341 |       dots.appendChild(dot);
342 |     });
343 | 
344 |     // Save elements
345 |     const secWrapper = html`
346 |       

347 |     ` as HTMLElement;
348 |     secWrapper.firstElementChild!.append(...sec.cloneNode(true).childNodes);
349 | 
350 |     // `row` is 
, and `inner` is ``
351 |     const row = createTocListItem(secWrapper, sec.id);
352 |     const inner = row.firstChild!;
353 | 
354 |     inner.appendChild(dots);
355 |     inner.appendChild(html`
356 |       ${countPriorityLevels(levels)!.report}
357 |     `);
358 | 
359 |     ol.appendChild(row);
360 |   }
361 | }
362 | 
363 | interface Configuration {
364 |   /** only generate a TOC so many levels deep */
365 |   maxTocLevel?: number;
366 | }
367 | export function createStructure(conf: Configuration = {}): void {
368 |   const sectionTree = getSectionTree(document.body);
369 |   const result = scanSections(sectionTree, conf.maxTocLevel ?? Infinity);
370 |   if (result) {
371 |     createTableOfContents(result);
372 |   }
373 | 
374 |   addPermalinks();
375 | 
376 |   const topSectionLevels = insertPriorityLevel(sectionTree)!;
377 |   createSummary(topSectionLevels);
378 | }
379 | 


--------------------------------------------------------------------------------
/src/respec/base.css:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * The following styles control the Table of Contents
  3 |  * They are selectively copied from W3C/ReSpec under CC0-1.0 license
  4 |  * https://github.com/speced/bikeshed/blob/527e9641607d686e5c439f9999d40360607ee792/bikeshed/spec-data/readonly/boilerplate/stylesheet.include
  5 |  * https://w3.org/StyleSheets/TR/2021/base.css
  6 |  */
  7 | 
  8 | /******************************************************************************/
  9 | /*                                  Colors                                    */
 10 | /******************************************************************************/
 11 | 
 12 | /* Any --*-text not paired with a --*-bg is assumed to have a transparent bg */
 13 | :root {
 14 | 	--text: black;
 15 | 	--bg: white;
 16 | 
 17 | 	/* Absolute URLs due to https://bugs.webkit.org/show_bug.cgi?id=230243 */
 18 | 	--unofficial-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-light-unofficial.svg);
 19 | 	--draft-watermark: url(https://www.w3.org/StyleSheets/TR/2021/logos/UD-watermark-light-draft.svg);
 20 | 
 21 | 	--logo-bg: #1a5e9a;
 22 | 	--logo-active-bg: #c00;
 23 | 	--logo-text: white;
 24 | 
 25 | 	--tocnav-normal-text: #707070;
 26 | 	--tocnav-normal-bg: var(--bg);
 27 | 	--tocnav-hover-text: var(--tocnav-normal-text);
 28 | 	--tocnav-hover-bg: #f8f8f8;
 29 | 	--tocnav-active-text: #c00;
 30 | 	--tocnav-active-bg: var(--tocnav-normal-bg);
 31 | 
 32 | 	--tocsidebar-text: var(--text);
 33 | 	--tocsidebar-bg: #f7f8f9;
 34 | 	--tocsidebar-shadow: rgba(0,0,0,.1);
 35 | 	--tocsidebar-heading-text: hsla(203,20%,40%,.7);
 36 | 
 37 | 	--toclink-text: var(--text);
 38 | 	--toclink-underline: #3980b5;
 39 | 	--toclink-visited-text: var(--toclink-text);
 40 | 	--toclink-visited-underline: #054572;
 41 | 
 42 | 	--heading-text: #005a9c;
 43 | 
 44 | 	--hr-text: var(--text);
 45 | 
 46 | 	--algo-border: #def;
 47 | 
 48 | 	--del-text: #AA0000;
 49 | 	--del-bg: transparent;
 50 | 	--ins-text: #006100;
 51 | 	--ins-bg: transparent;
 52 | 
 53 | 	--a-normal-text: #034575;
 54 | 	--a-normal-underline: #707070;
 55 | 	--a-visited-text: var(--a-normal-text);
 56 | 	--a-visited-underline: #bbb;
 57 | 	--a-hover-bg: rgba(75%, 75%, 75%, .25);
 58 | 	--a-active-text: #c00;
 59 | 	--a-active-underline: #c00;
 60 | 
 61 | 	--blockquote-border: silver;
 62 | 	--blockquote-bg: transparent;
 63 | 	--blockquote-text: var(--text);
 64 | 
 65 | 	--issue-border: #e05252;
 66 | 	--issue-bg: #fbe9e9;
 67 | 	--issue-text: var(--text);
 68 | 	--issueheading-text: #831616;
 69 | 
 70 | 	--example-border: #e0cb52;
 71 | 	--example-bg: #fcfaee;
 72 | 	--example-text: var(--text);
 73 | 	--exampleheading-text: #574b0f;
 74 | 
 75 | 	--note-border: #52e052;
 76 | 	--note-bg: #e9fbe9;
 77 | 	--note-text: var(--text);
 78 | 	--noteheading-text: hsl(120, 70%, 22%);
 79 | 	--notesummary-underline: silver;
 80 | 
 81 | 	--advisement-border: orange;
 82 | 	--advisement-bg: #fec;
 83 | 	--advisement-text: var(--text);
 84 | 	--advisementheading-text: #b35f00;
 85 | 
 86 | 	--amendment-border: #330099;
 87 | 	--amendment-bg: #F5F0FF;
 88 | 	--amendment-text: var(--text);
 89 | 	--amendmentheading-text: #220066;
 90 | 
 91 | 	--warning-border: red;
 92 | 	--warning-bg: hsla(40,100%,50%,0.95);
 93 | 	--warning-text: var(--text);
 94 | 
 95 | 	--def-border: #8ccbf2;
 96 | 	--def-bg: #def;
 97 | 	--def-text: var(--text);
 98 | 	--defrow-border: #bbd7e9;
 99 | 
100 | 	--datacell-border: silver;
101 | 
102 | 	--indexinfo-text: #707070;
103 | 
104 | 	--indextable-hover-text: black;
105 | 	--indextable-hover-bg: #f7f8f9;
106 | 
107 | 	--outdatedspec-bg: rgba(0, 0, 0, .5);
108 | 	--outdatedspec-text: black;
109 | 	--outdated-bg: maroon;
110 | 	--outdated-text: white;
111 | 	--outdated-shadow: red;
112 | 
113 | 	--editedrec-bg: darkorange;
114 | }
115 | 
116 | 
117 | /******************************************************************************/
118 | /*                         Front Matter & Navigation                          */
119 | /******************************************************************************/
120 | 
121 | 
122 | /** Back to Top / ToC Toggle **************************************************/
123 | 
124 | 	@media print {
125 | 		#toc-nav {
126 | 			display: none;
127 | 		}
128 | 	}
129 | 	@media not print {
130 | 		#toc-nav {
131 | 			position: fixed;
132 | 			z-index: 3;
133 | 			bottom: 0; left: 0;
134 | 			margin: 0;
135 | 			min-width: 1.33em;
136 | 			border-top-right-radius: 2rem;
137 | 			box-shadow: 0 0 2px;
138 | 			font-size: 1.5em;
139 | 		}
140 | 		#toc-nav > a {
141 | 			display: block;
142 | 			white-space: nowrap;
143 | 
144 | 			height: 1.33em;
145 | 			padding: .1em 0.3em;
146 | 			margin: 0;
147 | 
148 | 			box-shadow: 0 0 2px;
149 | 			border: none;
150 | 			border-top-right-radius: 1.33em;
151 | 
152 | 			color: #707070;
153 | 			color: var(--tocnav-normal-text);
154 | 			background: white;
155 | 			background: var(--tocnav-normal-bg);
156 | 		}
157 | 		#toc-nav > a:hover,
158 | 		#toc-nav > a:focus {
159 | 			color: black;
160 | 			color: var(--tocnav-hover-text);
161 | 			background: #f8f8f8;
162 | 			background: var(--tocnav-hover-bg);
163 | 		}
164 | 		#toc-nav > a:active {
165 | 			color: #c00;
166 | 			color: var(--tocnav-active-text);
167 | 			background: white;
168 | 			background: var(--tocnav-active-bg);
169 | 		}
170 | 
171 | 		#toc-nav > #toc-jump,
172 | 		#toc-nav > #toc-toggle {
173 | 			padding-bottom: 2em;
174 | 			margin-bottom: -1.9em;
175 | 		}
176 | 
177 | 		/* statusbar gets in the way on keyboard focus; remove once browsers fix */
178 | 		#toc-nav > a[href="#toc"]:not(:hover):focus:last-child {
179 | 			padding-bottom: 1.5rem;
180 | 		}
181 | 
182 | 		#toc-nav:not(:hover) > a:not(:focus) > span + span {
183 | 			/* Ideally this uses :focus-within on #toc-nav */
184 | 			display: none;
185 | 		}
186 | 		#toc-nav > a > span + span {
187 | 			padding-right: 0.2em;
188 | 		}
189 | 	}
190 | 
191 | /** ToC Sidebar ***************************************************************/
192 | 
193 | 	/* Floating sidebar */
194 | 	@media screen {
195 | 		body.toc-sidebar #toc {
196 | 			position: fixed;
197 | 			top: 0; bottom: 0;
198 | 			left: 0;
199 | 			width: 23.5em;
200 | 			max-width: 80%;
201 | 			max-width: calc(100% - 2em - 26px);
202 | 			overflow: auto;
203 | 			padding: 0 1em;
204 | 			padding-left: 42px;
205 | 			padding-left: calc(1em + 26px);
206 | 			color: black;
207 | 			color: var(--tocsidebar-text);
208 | 			background: inherit;
209 | 			background-color: #f7f8f9;
210 | 			background-color: var(--tocsidebar-bg);
211 | 			z-index: 1;
212 | 			box-shadow: -.1em 0 .25em rgba(0,0,0,.1) inset;
213 | 			box-shadow: -.1em 0 .25em var(--tocsidebar-shadow) inset;
214 | 		}
215 | 		body.toc-sidebar #toc h2 {
216 | 			margin-top: .8rem;
217 | 			font-variant: small-caps;
218 | 			font-variant: all-small-caps;
219 | 			text-transform: lowercase;
220 | 			font-weight: bold;
221 | 			color: gray;
222 | 			color: hsla(203,20%,40%,.7);
223 | 			color: var(--tocsidebar-heading-text);
224 | 		}
225 | 		body.toc-sidebar #toc-jump:not(:focus) {
226 | 			width: 0;
227 | 			height: 0;
228 | 			padding: 0;
229 | 			position: absolute;
230 | 			overflow: hidden;
231 | 		}
232 | 	}
233 | 	/* Hide main scroller when only the ToC is visible anyway */
234 | 	@media screen and (max-width: 28em) {
235 | 		body.toc-sidebar {
236 | 			overflow: hidden;
237 | 		}
238 | 	}
239 | 
240 | 	/* Sidebar with its own space */
241 | 	@media screen and (min-width: 78em) {
242 | 		body:not(.toc-inline) #toc {
243 | 			position: fixed;
244 | 			top: 0; bottom: 0;
245 | 			left: 0;
246 | 			width: 23.5em;
247 | 			overflow: auto;
248 | 			padding: 0 1em;
249 | 			padding-left: 42px;
250 | 			padding-left: calc(1em + 26px);
251 | 			color: black;
252 | 			color: var(--tocsidebar-text);
253 | 			background: inherit;
254 | 			background-color: #f7f8f9;
255 | 			background-color: var(--tocsidebar-bg);
256 | 			z-index: 1;
257 | 			box-shadow: -.1em 0 .25em rgba(0,0,0,.1) inset;
258 | 			box-shadow: -.1em 0 .25em var(--tocsidebar-shadow) inset;
259 | 		}
260 | 		body:not(.toc-inline) #toc h2 {
261 | 			margin-top: .8rem;
262 | 			font-variant: small-caps;
263 | 			font-variant: all-small-caps;
264 | 			text-transform: lowercase;
265 | 			font-weight: bold;
266 | 			color: gray;
267 | 			color: hsla(203,20%,40%,.7);
268 | 			color: var(--tocsidebar-heading-text);
269 | 		}
270 | 
271 | 		body:not(.toc-inline) {
272 | 			padding-left: 29em;
273 | 		}
274 | 		/* See also Overflow section at the bottom */
275 | 
276 | 		body:not(.toc-inline) #toc-jump:not(:focus) {
277 | 			width: 0;
278 | 			height: 0;
279 | 			padding: 0;
280 | 			position: absolute;
281 | 			overflow: hidden;
282 | 		}
283 | 	}
284 | 	@media screen and (min-width: 90em) {
285 | 		body:not(.toc-inline) {
286 | 			margin: 0 4em;
287 | 		}
288 | 	}
289 | 
290 | 
291 | /******************************************************************************/
292 | /*                                  Indices                                   */
293 | /******************************************************************************/
294 | 
295 | 
296 | /** Table of Contents *********************************************************/
297 | 
298 | 	.toc a {
299 | 		color: var(--toclink-text);
300 | 		/* More spacing; use padding to make it part of the click target. */
301 | 		padding: 0.1rem 1px 0;
302 | 		/* Larger, more consistently-sized click target */
303 | 		display: block;
304 | 		/* Switch to using border-bottom */
305 | 		text-decoration: none;
306 | 		border-bottom: 3px solid transparent;
307 | 		margin-bottom: -2px;
308 | 	}
309 | 	.toc a:visited {
310 | 		color: black;
311 | 		color: var(--toclink-visited-text);
312 | 	}
313 | 	.toc a:focus,
314 | 	.toc a:hover {
315 | 		background: #f8f8f8;
316 | 		background: rgba(75%, 75%, 75%, .25);
317 | 		background: var(--a-hover-bg);
318 | 		border-bottom-color: #3980b5;
319 | 		border-bottom-color: var(--toclink-underline);
320 | 	}
321 | 	.toc a:visited:focus,
322 | 	.toc a:visited:hover {
323 | 		border-bottom-color: #054572;
324 | 		border-bottom-color: var(--toclink-visited-underline);
325 | 	}
326 | 
327 | 	.toc, .toc ol, .toc ul, .toc li {
328 | 		list-style: none; /* Numbers must be inlined into source */
329 | 		/* because generated content isn't search/selectable and markers can't do multilevel yet */
330 | 		margin:  0;
331 | 		padding: 0;
332 | 	}
333 | 	.toc {
334 | 		line-height: 1.1em; /* consistent spacing */
335 | 	}
336 | 
337 | 	/* ToC not indented until third level, but font style & margins show hierarchy */
338 | 	.toc > li             { font-weight: bold;   }
339 | 	.toc > li li          { font-weight: normal; }
340 | 	.toc > li li li       { font-size:   95%;    }
341 | 	.toc > li li li li    { font-size:   90%;    }
342 | 	.toc > li li li li li { font-size:   85%;    }
343 | 
344 | 	.toc > li             { margin: 1.5rem 0;    }
345 | 	.toc > li li          { margin: 0.3rem 0;    }
346 | 	.toc > li li li       { margin-left: 2rem;   }
347 | 
348 | 	/* Section numbers in a column of their own */
349 | 	.toc .secno {
350 | 		float: left;
351 | 		width: 4rem;
352 | 		white-space: nowrap;
353 | 	}
354 | 	.toc > li li li li .secno {
355 | 		font-size: 85%;
356 | 	}
357 | 	.toc > li li li li li .secno {
358 | 		font-size: 100%;
359 | 	}
360 | 
361 | 	:not(li) > .toc              { margin-left:  5rem; }
362 | 	.toc .secno                  { margin-left: -5rem; }
363 | 	.toc > li li li .secno       { margin-left: -7rem; }
364 | 	.toc > li li li li .secno    { margin-left: -9rem; }
365 | 	.toc > li li li li li .secno { margin-left: -11rem; }
366 | 
367 | 	/* Tighten up indentation in narrow ToCs */
368 | 	@media (max-width: 30em) {
369 | 		:not(li) > .toc              { margin-left:  4rem; }
370 | 		.toc .secno                  { margin-left: -4rem; }
371 | 		.toc > li li li              { margin-left:  1rem; }
372 | 		.toc > li li li .secno       { margin-left: -5rem; }
373 | 		.toc > li li li li .secno    { margin-left: -6rem; }
374 | 		.toc > li li li li li .secno { margin-left: -7rem; }
375 | 	}
376 | 	@media screen and (min-width: 78em) {
377 | 		body:not(.toc-inline) :not(li) > .toc              { margin-left:  4rem; }
378 | 		body:not(.toc-inline) .toc .secno                  { margin-left: -4rem; }
379 | 		body:not(.toc-inline) .toc > li li li              { margin-left:  1rem; }
380 | 		body:not(.toc-inline) .toc > li li li .secno       { margin-left: -5rem; }
381 | 		body:not(.toc-inline) .toc > li li li li .secno    { margin-left: -6rem; }
382 | 		body:not(.toc-inline) .toc > li li li li li .secno { margin-left: -7rem; }
383 | 	}
384 | 	body.toc-sidebar #toc :not(li) > .toc              { margin-left:  4rem; }
385 | 	body.toc-sidebar #toc .toc .secno                  { margin-left: -4rem; }
386 | 	body.toc-sidebar #toc .toc > li li li              { margin-left:  1rem; }
387 | 	body.toc-sidebar #toc .toc > li li li .secno       { margin-left: -5rem; }
388 | 	body.toc-sidebar #toc .toc > li li li li .secno    { margin-left: -6rem; }
389 | 	body.toc-sidebar #toc .toc > li li li li li .secno { margin-left: -7rem; }
390 | 
391 | 	.toc li {
392 | 		clear: both;
393 | 	}
394 | 
395 | 


--------------------------------------------------------------------------------
/scripts/check_issues.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Check issues mentioned in the document or reported in typst repositories.
  3 |  *
  4 |  * Save the report to `report.md` (`steps.{id}.outputs.report-file`) and `$GITHUB_STEP_SUMMARY` (if exists).
  5 |  *
  6 |  * All specified checks will be executed, even if an early check failed.
  7 |  *
  8 |  * Prerequisite: https://cli.github.com.
  9 |  */
 10 | 
 11 | import assert from "node:assert";
 12 | import { writeFile } from "node:fs/promises";
 13 | import { env } from "node:process";
 14 | import { fileURLToPath } from "node:url";
 15 | 
 16 | import { zip } from "es-toolkit";
 17 | 
 18 | import { extraArgs } from "./config.ts";
 19 | import { typst } from "./typst.ts";
 20 | import { duration_fmt, execFile } from "./util.ts";
 21 | 
 22 | interface RepoNum {
 23 |   repo: string;
 24 |   num: string;
 25 | }
 26 | export interface IssueMeta extends RepoNum {
 27 |   note: string;
 28 |   closed: boolean;
 29 | }
 30 | export interface PullMeta extends RepoNum {
 31 |   merged: boolean;
 32 |   rejected: boolean;
 33 | }
 34 | 
 35 | type IssueState =
 36 |   & { title: string }
 37 |   & ({
 38 |     state: "OPEN";
 39 |     stateReason: string | null;
 40 |     closed: false;
 41 |     closedAt: null;
 42 |   } | {
 43 |     state: "CLOSED";
 44 |     stateReason: string;
 45 |     closed: true;
 46 |     closedAt: string;
 47 |   });
 48 | 
 49 | type PullState =
 50 |   & { title: string }
 51 |   & (
 52 |     | {
 53 |       state: "OPEN";
 54 |       merged: false;
 55 |       closed: false;
 56 |       closedAt: null;
 57 |     }
 58 |     | { closed: true; closedAt: string }
 59 |       & ({
 60 |         state: "MERGED";
 61 |         merged: true;
 62 |       } | {
 63 |         state: "CLOSED";
 64 |         merged: false;
 65 |       })
 66 |   );
 67 | 
 68 | /**
 69 |  * Grouped by `repo` and `num`, and flattened
 70 |  *
 71 |  * E.g., an array of `[IssueMeta[] of an issue in a repo]`.
 72 |  */
 73 | type GroupedFlat = T[][];
 74 | 
 75 | /**
 76 |  * Grouped by `repo` and `num`
 77 |  *
 78 |  * repo ⇒ num ⇒ `T[]` of this repo and num.
 79 |  */
 80 | type Grouped = Map;
 81 | 
 82 | function flattenGrouped(
 83 |   grouped: Grouped,
 84 | ): GroupedFlat {
 85 |   return Array.from(grouped.values()).flat().map(([_num, meta]) => meta);
 86 | }
 87 | 
 88 | function parseRepo(
 89 |   repo: string,
 90 | ): { owner: string; name: string; repoSanitized: string } {
 91 |   const [owner, name] = repo.split("/", 2);
 92 |   const repoSanitized = repo.replaceAll(/[\/-]/g, "_");
 93 |   return { owner, name, repoSanitized };
 94 | }
 95 | 
 96 | /**
 97 |  * Error handling with the `Result` type.
 98 |  * https://doc.rust-lang.org/stable/std/result/
 99 |  */
100 | class Result {
101 |   succeeded: boolean;
102 |   /** Markdown message */
103 |   message: string;
104 | 
105 |   constructor(succeeded: boolean, message: string) {
106 |     this.succeeded = succeeded;
107 |     this.message = message;
108 |   }
109 | 
110 |   static Ok(message: string): Result {
111 |     return new Result(true, message);
112 |   }
113 | 
114 |   static Err(message: string): Result {
115 |     return new Result(false, message);
116 |   }
117 | 
118 |   join(other: Result): Result {
119 |     return new Result(
120 |       this.succeeded && other.succeeded,
121 |       [this.message, other.message].join("\n\n"),
122 |     );
123 |   }
124 | }
125 | 
126 | /** Get issues and pull requests in the typst document. */
127 | async function queryDocument(): Promise<
128 |   { issues: IssueMeta[]; pulls: PullMeta[] }
129 | > {
130 |   const timeStart = Date.now();
131 | 
132 |   const data = JSON.parse(
133 |     await typst([
134 |       "query",
135 |       "main.typ",
136 |       "selector().or()",
137 |       "--target=html",
138 |       ...extraArgs.pre,
139 |     ]),
140 |   ) as { func: "metadata"; value: object; label: "" | "" }[];
141 | 
142 |   console.log(
143 |     `📃 Got ${data.length} results from typst query successfully in`,
144 |     `${duration_fmt(Date.now() - timeStart)}.`,
145 |   );
146 | 
147 |   return {
148 |     issues: data.filter((d) => d.label === "").map((d) =>
149 |       d.value as IssueMeta
150 |     ),
151 |     pulls: data.filter((d) => d.label === "").map((d) =>
152 |       d.value as PullMeta
153 |     ),
154 |   };
155 | }
156 | 
157 | /**
158 |  * Checks if there are any duplicate issues.
159 |  *
160 |  * Most issues should be linked only once.
161 |  * If an issue truly needs to be linked multiple times (e.g., it involves multiple problems),
162 |  * add a note to clarify. For example:
163 |  *
164 |  * ```typst
165 |  * #issue("hayagriva#189", note: [mentioned])
166 |  * ```
167 |  */
168 | function assertUniq(issues: IssueMeta[]): Result {
169 |   const suspiciousDest = issues.filter(({ note }) => note === "auto").map((
170 |     { repo, num },
171 |   ) => `${repo}#${num}`);
172 |   const duplicates = suspiciousDest.filter((item, index) =>
173 |     suspiciousDest.indexOf(item) !== index
174 |   );
175 | 
176 |   if (duplicates.length > 0) {
177 |     return Result.Err(`Duplicated issues found:\n${new Set(duplicates)}`);
178 |   } else {
179 |     return Result.Ok("All issues are unique.");
180 |   }
181 | }
182 | 
183 | /**
184 |  * Query GitHub GraphQL API using GitHub CLI.
185 |  * https://docs.github.com/en/graphql/reference/queries
186 |  */
187 | async function queryGitHub(query: string): Promise {
188 |   const timeStart = Date.now();
189 | 
190 |   const { stdout } = await execFile("gh", [
191 |     "api",
192 |     "graphql",
193 |     "--raw-field",
194 |     `query=${query}`,
195 |   ]);
196 | 
197 |   console.log(
198 |     `📩 Got ${stdout.length} characters from GitHub API successfully in`,
199 |     `${duration_fmt(Date.now() - timeStart)}.`,
200 |   );
201 | 
202 |   return JSON.parse(stdout).data;
203 | }
204 | 
205 | function groupByRepoNum(meta_list: T[]): Grouped {
206 |   const repos = new Set(meta_list.map((i) => i.repo));
207 | 
208 |   const grouped = new Map(
209 |     Array.from(repos.values()).map(
210 |       (repo) => {
211 |         const concerned = meta_list.filter((i) => repo === i.repo);
212 |         const numUniq = Array.from(
213 |           (new Set(concerned.map(({ num }) => num))).values(),
214 |         );
215 |         return [
216 |           repo,
217 |           numUniq.map((n) =>
218 |             [n, concerned.filter(({ num }) => n === num)] as [string, T[]]
219 |           ),
220 |         ];
221 |       },
222 |     ),
223 |   );
224 |   return grouped;
225 | }
226 | 
227 | /**
228 |  * @returns query The GraphQL query without wrapping `query { }`.
229 |  * @returns grouped
230 |  */
231 | function generateIssuesQuery(
232 |   issues: IssueMeta[],
233 | ): { query: string; grouped: GroupedFlat } {
234 |   const grouped = groupByRepoNum(issues);
235 | 
236 |   const query = [
237 |     ...Array.from(grouped.entries()).map(([repo, issues]) => {
238 |       const { owner, name, repoSanitized } = parseRepo(repo);
239 |       return [
240 |         `  ${repoSanitized}_issues: repository(owner: "${owner}", name: "${name}") {`,
241 |         ...issues.map(([num, _meta]) =>
242 |           `    issue_${num}: issue(number: ${num}) { title state stateReason closed closedAt }`
243 |         ),
244 |         "  }",
245 |       ];
246 |     }),
247 |   ].flat().join("\n");
248 | 
249 |   return { query, grouped: flattenGrouped(grouped) };
250 | }
251 | 
252 | /**
253 |  * @returns query The GraphQL query without wrapping `query { }`.
254 |  * @returns grouped
255 |  */
256 | function generatePullsQuery(
257 |   pulls: PullMeta[],
258 | ): { query: string; grouped: GroupedFlat } {
259 |   const grouped = groupByRepoNum(pulls);
260 | 
261 |   const query = [
262 |     ...Array.from(grouped.entries()).map(([repo, pulls]) => {
263 |       const { owner, name, repoSanitized } = parseRepo(repo);
264 |       return [
265 |         `  ${repoSanitized}_pulls: repository(owner: "${owner}", name: "${name}") {`,
266 |         ...pulls.map(([num, _meta]) =>
267 |           `    pull_${num}: pullRequest(number: ${num}) { title state merged closed closedAt }`
268 |         ),
269 |         "  }",
270 |       ];
271 |     }),
272 |   ].flat().join("\n");
273 | 
274 |   return { query, grouped: flattenGrouped(grouped) };
275 | }
276 | 
277 | /**
278 |  * Fetch states of issues and pull requests.
279 |  *
280 |  * Duplicate issues or pull requests will be collected into a single entry.
281 |  */
282 | async function fetchStates(
283 |   issues: IssueMeta[],
284 |   pulls: PullMeta[],
285 | ): Promise<
286 |   { issues: [IssueMeta[], IssueState][]; pulls: [PullMeta[], PullState][] }
287 | > {
288 |   const meta = {
289 |     issues: generateIssuesQuery(issues),
290 |     pulls: generatePullsQuery(pulls),
291 |   };
292 | 
293 |   const query = [
294 |     "query {",
295 |     meta.issues.query,
296 |     meta.pulls.query,
297 |     "}",
298 |   ].join("\n");
299 | 
300 |   const data = await queryGitHub(query) as Record<
301 |     string,
302 |     Record
303 |   >;
304 | 
305 |   const stateFlat = Object.values(data).map((issues_or_pulls_of_repo) =>
306 |     Object.values(issues_or_pulls_of_repo)
307 |   ).flat();
308 | 
309 |   assert.strictEqual(
310 |     stateFlat.length,
311 |     meta.issues.grouped.length + meta.pulls.grouped.length,
312 |   );
313 | 
314 |   const state = {
315 |     issues: stateFlat.slice(0, meta.issues.grouped.length) as IssueState[],
316 |     pulls: stateFlat.slice(meta.issues.grouped.length) as PullState[],
317 |   };
318 | 
319 |   return {
320 |     issues: zip(meta.issues.grouped, state.issues),
321 |     pulls: zip(meta.pulls.grouped, state.pulls),
322 |   };
323 | }
324 | 
325 | /**
326 |  * Checks if all issues’ states are up to date.
327 |  *
328 |  * Most issues should be open.
329 |  * If a closed issue is truly needed (e.g., duplicated but cleaner),
330 |  * add a note to clarify. For example:
331 |  *
332 |  * ```typst
333 |  * #issue("hayagriva#189", closed: true)
334 |  * ```
335 |  */
336 | function assertIssuesStateUpdated(states: [IssueMeta[], IssueState][]): Result {
337 |   const outdated = states.filter(([meta, state]) =>
338 |     meta.some((m) => m.closed !== state.closed)
339 |   );
340 | 
341 |   if (outdated.length > 0) {
342 |     const message = outdated.map(([meta, state]) => {
343 |       const stateHuman = state.closed
344 |         ? `closed at ${state.closedAt} for ${state.stateReason}`
345 |         : `open${state.stateReason ? ` for ${state.stateReason}` : ""}`;
346 | 
347 |       const metaHuman = meta.map((m) =>
348 |         `(note: ${m.note}, closed: ${m.closed})`
349 |       ).join(" ");
350 | 
351 |       return [
352 |         `- ${meta[0].repo}#${meta[0].num} ${state.title} (${stateHuman})`,
353 |         `  ${metaHuman}`,
354 |       ];
355 |     }).flat().join("\n");
356 |     return Result.Err(`Outdated issues found:\n${message}`);
357 |   } else {
358 |     return Result.Ok("All issues’ states are up to date.");
359 |   }
360 | }
361 | 
362 | /** Checks if all pull requests’ states are up to date. */
363 | function assertPullsStateUpdated(states: [PullMeta[], PullState][]): Result {
364 |   const outdated = states.filter(([meta, state]) =>
365 |     meta.some((m) =>
366 |       m.merged !== state.merged ||
367 |       m.rejected !== (state.closed && !state.merged)
368 |     )
369 |   );
370 | 
371 |   if (outdated.length > 0) {
372 |     const message = outdated.map(([meta, state]) => {
373 |       const stateHuman = state.state === "OPEN"
374 |         ? "open"
375 |         : `${
376 |           state.state.toLowerCase().replace("closed", "rejected")
377 |         } at ${state.closedAt}`;
378 |       return `- ${meta[0].repo}#${meta[0].num} ${state.title} (${stateHuman})`;
379 |     }).join("\n");
380 |     return Result.Err(`Outdated pull requests found:\n${message}`);
381 |   } else {
382 |     return Result.Ok("All pull requests’ states are up to date.");
383 |   }
384 | }
385 | 
386 | interface WatchTarget {
387 |   repo: string;
388 |   labels: string[];
389 | }
390 | 
391 | type LatestIssue = {
392 |   repo: string;
393 |   num: string;
394 |   title: string;
395 |   stateReason: string | null;
396 | };
397 | 
398 | /** Fetches latest open issues from multiple GitHub repositories. */
399 | async function fetchLatestIssues(
400 |   watches: WatchTarget[],
401 | ): Promise {
402 |   const query = [
403 |     "query {",
404 |     ...watches.map(({ repo, labels }) => {
405 |       const { owner, name, repoSanitized } = parseRepo(repo);
406 |       return `
407 |         ${repoSanitized}: repository(owner: "${owner}", name: "${name}") {
408 |           issues(
409 |             labels: ${JSON.stringify(labels)}
410 |             first: 30,
411 |             states: [OPEN],
412 |             orderBy: { direction: DESC, field: UPDATED_AT }
413 |           ) {
414 |             nodes { number title stateReason }
415 |           }
416 |         }`;
417 |     }),
418 |     "}",
419 |   ].join("\n");
420 | 
421 |   const data = await queryGitHub(query) as Record<
422 |     string,
423 |     {
424 |       issues: {
425 |         nodes: { number: number; title: string; stateReason: string | null }[];
426 |       };
427 |     }
428 |   >;
429 | 
430 |   const dataFlat = Object.values(data).map((repo) => repo.issues.nodes);
431 | 
432 |   return watches.map(({ repo }, index) =>
433 |     dataFlat[index].map(({ number, title, stateReason }) => ({
434 |       repo,
435 |       num: number.toString(),
436 |       title,
437 |       stateReason,
438 |     }))
439 |   ).flat();
440 | }
441 | 
442 | /** Checks if all latest issues are covered in the document. */
443 | function assertAllCovered(issues: IssueMeta[], latest: LatestIssue[]): Result {
444 |   const uncovered = latest.filter(({ repo, num }) =>
445 |     !issues.some((i) => i.repo === repo && i.num === num)
446 |   );
447 | 
448 |   if (uncovered.length > 0) {
449 |     const message = uncovered.map(({ repo, num, title, stateReason }) =>
450 |       `- ${repo}#${num} ${stateReason ? `(${stateReason}) ` : ""}${title}`
451 |     ).join("\n");
452 |     return Result.Err(`Uncovered latest issues found:\n${message}`);
453 |   } else {
454 |     return Result.Ok("All latest issues are covered.");
455 |   }
456 | }
457 | 
458 | if (process.argv[1] === fileURLToPath(import.meta.url)) {
459 |   const argv = process.argv.slice(2);
460 |   const checkAllCovered = argv.includes("--assert-all-covered");
461 | 
462 |   const { issues, pulls } = await queryDocument();
463 | 
464 |   let result = assertUniq(issues);
465 | 
466 |   const states = await fetchStates(issues, pulls);
467 |   result = result.join(assertIssuesStateUpdated(states.issues));
468 |   result = result.join(assertPullsStateUpdated(states.pulls));
469 | 
470 |   if (checkAllCovered) {
471 |     const latest = await fetchLatestIssues([
472 |       { repo: "typst/typst", labels: ["cjk"] },
473 |       { repo: "typst/hayagriva", labels: ["i18n"] },
474 |     ]);
475 |     result = result.join(assertAllCovered(issues, latest));
476 |   }
477 | 
478 |   await writeFile("report.md", result.message + "\n", { flag: "w" });
479 |   if (env.GITHUB_OUTPUT) {
480 |     await writeFile(env.GITHUB_OUTPUT, "report-file=report.md", { flag: "a" });
481 |   }
482 |   if (env.GITHUB_STEP_SUMMARY) {
483 |     await writeFile(env.GITHUB_STEP_SUMMARY, result.message + "\n", {
484 |       flag: "a",
485 |     });
486 |   }
487 |   process.exit(result.succeeded ? 0 : 1);
488 | }
489 | 


--------------------------------------------------------------------------------
127 | Contents 128 | 目录 129 |
