docs: generate typlite readme (#1868)

* docs: generate typltie readme

* dev(ci): add docs check

* fix: don't cache error

* dev(ci): install typst

* docs: update docs

* feat: mark shell scripts

.github/workflows/ci.yml

@@ -38,6 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: typst-community/setup-typst@v4
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           components: clippy, rustfmt
@@ -56,6 +57,8 @@ jobs:
       - run: scripts/feature-testing.sh
       - run: cargo fmt --check --all
       - run: cargo doc --workspace --no-deps
+      - run: yarn build:typlite
+      - run: node ./scripts/link-docs.mjs --check
       - name: Generate completions
         run: |
           mkdir -p completions/{zsh,bash,fish/vendor_completions.d,elvish/lib,nushell/vendor/autoload,powershell}/

crates/typlite/README.md

@@ -1,11 +1,20 @@
+<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/crates/typlite.typ. Do not edit manually. -->
 # Typlite
 
 Converts a subset of typst to markdown.
 
 ## Installation
 
+### Install prebuilt binaries via shell script
+
+```sh
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/tinymist/releases/download/v0.13.14/typlite-installer.sh | sh
 ```
-cargo install typlite
+
+### Install prebuilt binaries via powershell script
+
+```ps1
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/Myriad-Dreamin/tinymist/releases/download/v0.13.14/typlite-installer.ps1 | iex"
 ```
 
 ## Usage

docs/tinymist/crates/typlite.typ

@@ -0,0 +1,69 @@
+#show raw.where(lang: "sh"): it => [#it#metadata(it.text)<shell-script>]
+
+Converts a subset of typst to markdown.
+
+= Installation
+
+#let typlite-ver = toml("/crates/typlite/Cargo.toml").package.version
+#if type(typlite-ver) == dictionary and typlite-ver.workspace == true {
+  typlite-ver = toml("/Cargo.toml").workspace.package.version
+}
+
+== Install prebuilt binaries via shell script
+
+#raw(lang: "sh", block: true, {
+  "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/tinymist/releases/download/v"
+  typlite-ver
+  "/typlite-installer.sh | sh"
+})
+
+
+== Install prebuilt binaries via powershell script
+
+#raw(lang: "ps1", block: true, {
+  "powershell -ExecutionPolicy Bypass -c \"irm https://github.com/Myriad-Dreamin/tinymist/releases/download/v"
+  typlite-ver
+  "/typlite-installer.ps1 | iex\""
+})
+
+
+= Usage
+
+```shell
+# default output is main.md
+typlite main.typ
+# specify output
+typlite main.typ output.md
+```
+
+Supported format:
+
+- `output.txt`: Plain text
+- `output.md`: Markdown
+- `output.tex`: LaTeX
+- `output.docx`: Word
+
+Todo: We may support custom format by typst scripting in future, like:
+
+```shell
+# specify output
+typlite main.typ --post-process @preview/typlite-mdx output.mdx
+```
+
+= Feature
+
+- *Contexual Content Rendering*: Contents begin with `context` keyword will be rendered as svg output. The svg output will be embedded inline in the output file as *base64* by default, if the `--assets-path` parameter is not specified. Otherwise, the svg output will be saved in the specified folder and the path will be embedded in the output file.
+
+= Typlite-Specific `sys.inputs`
+
+The `sys.input.x-target` can be used distinguish with normal HTML export.
+
+```typ
+#let x-target = sys.inputs.at("x-target", default: "pdf")
+
+#let my-function = if x-target == "md" {
+  md-impl
+} else {
+  pdf-impl or html-impl
+}
+```

scripts/link-docs.mjs

@@ -113,34 +113,77 @@ const maintainerMd = async () => {
   await fs.promises.writeFile(outPath, outputContent);
 };
 
+const isCheck = process.argv.includes("--check");
+
+const tasks = [
+  {
+    input: "docs/tinymist/introduction.typ",
+    output: "README.md",
+    title: "Tinymist",
+  },
+  {
+    input: "docs/tinymist/release-instruction.typ",
+    output: "docs/release-instruction.md",
+    title: "Release Instructions",
+  },
+  {
+    input: "docs/tinymist/crates/typlite.typ",
+    output: "crates/typlite/README.md",
+    title: "Typlite",
+  },
+  {
+    input: "docs/tinymist/frontend/emacs.typ",
+    output: "editors/emacs/README.md",
+    title: "Tinymist Emacs Support for Typst",
+  },
+  {
+    input: "docs/tinymist/frontend/helix.typ",
+    output: "editors/helix/README.md",
+    title: "Tinymist Helix Support for Typst",
+  },
+  {
+    input: "docs/tinymist/frontend/neovim.typ",
+    output: "editors/neovim/README.md",
+    title: "Tinymist Neovim Support for Typst",
+  },
+  {
+    input: "docs/tinymist/frontend/sublime-text.typ",
+    output: "editors/sublime-text/README.md",
+    title: "Tinymist Sublime Support for Typst",
+  },
+  {
+    input: "docs/tinymist/frontend/vscode.typ",
+    output: "editors/vscode/README.md",
+    title: "Tinymist Typst VS Code Extension",
+  },
+  {
+    input: "docs/tinymist/frontend/zed.typ",
+    output: "editors/zed/README.md",
+    title: "Tinymist Zed Support for Typst",
+  },
+];
+
 const main = async () => {
   await Promise.all([
-    convert("docs/tinymist/introduction.typ", "README.md", {
-      before: "# Tinymist\n\n",
-    }),
-    convert("docs/tinymist/release-instruction.typ", "docs/release-instruction.md", {
-      before: "# Release Instructions\n\n",
-    }),
-    convert("docs/tinymist/frontend/emacs.typ", "editors/emacs/README.md", {
-      before: "# Tinymist Emacs Support for Typst\n\n",
-    }),
-    convert("docs/tinymist/frontend/helix.typ", "editors/helix/README.md", {
-      before: "# Tinymist Helix Support for Typst\n\n",
-    }),
-    convert("docs/tinymist/frontend/neovim.typ", "editors/neovim/README.md", {
-      before: "# Tinymist Neovim Support for Typst\n\n",
-    }),
-    convert("docs/tinymist/frontend/sublime-text.typ", "editors/sublime-text/README.md", {
-      before: "# Tinymist Sublime Support for Typst\n\n",
-    }),
-    convert("docs/tinymist/frontend/vscode.typ", "editors/vscode/README.md", {
-      before: "# Tinymist Typst VS Code Extension\n\n",
-    }),
-    convert("docs/tinymist/frontend/zed.typ", "editors/zed/README.md", {
-      before: "# Tinymist Zed Support for Typst\n\n",
-    }),
+    ...tasks.map((task) => convert(task.input, task.output, { before: `# ${task.title}\n\n` })),
     maintainerMd(),
   ]);
+
+  if (isCheck) {
+    // any dirty git files?
+    await Promise.all(
+      tasks.map(async (task) => {
+        const gitStatus = execSync(`git status --porcelain ${task.output}`, {
+          encoding: "utf-8",
+        }).trim();
+        if (gitStatus) {
+          throw new Error(
+            `The file ${task.output} is not up to date. Please run \`node scripts/link-docs.mjs\` to update it.`,
+          );
+        }
+      }),
+    );
+  }
 };
 
-main().catch(console.error);
+main();

typ/templates/page.typ

@@ -51,6 +51,7 @@
 #let part-counter = counter("shiroa-part-counter")
 
 #let md-equation-rules(body) = {
+  let gh-dark-fg = rgb("#f0f6fc")
   // equation setting
   show math.equation: it => theme-box(
     tag: if it.block { "p" } else { "span" },
@@ -460,7 +461,7 @@
   //   ```,
 
   // Put your custom CSS here.
-  context if shiroa-sys-target() == "html" {
+  context if not is-md-target and shiroa-sys-target() == "html" {
     html.elem(
       "style",
       ```css