feat: finally directly generate markdown files (#1881)

* feat: finally directly generate markdown files

* fix: trim

* fix: await

README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/introduction.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist
 
 Tinymist \[ˈtaɪni mɪst\] is an integrated language service for [Typst](https://typst.app/) \[taɪpst\]. You can also call it "微霭" \[wēi ǎi\] in Chinese.
@@ -125,11 +125,11 @@ See [Online Documentation](https://myriad-dreamin.github.io/tinymist/).
 
 Stable Channel:
 
-[Packaging status](https://repology.org/project/tinymist/versions)
+<a href="https://repology.org/project/tinymist/versions" target="_blank" rel="noopener noreferrer"><img src="https://repology.org/badge/vertical-allrepos/tinymist.svg" alt="Packaging status" style="max-width: 100%; height: auto;" /></a>
 
 Nightly Channel:
 
-[Packaging status](https://repology.org/project/tinymist-nightly/versions)
+<a href="https://repology.org/project/tinymist-nightly/versions" target="_blank" rel="noopener noreferrer"><img src="https://repology.org/badge/vertical-allrepos/tinymist-nightly.svg" alt="Packaging status" style="max-width: 100%; height: auto;" /></a>
 
 ## Roadmap
 

crates/typlite/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/crates/typlite.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Typlite
 
 Converts a subset of typst to markdown.

crates/typlite/src/lib.rs

@@ -3,7 +3,6 @@
 pub mod attributes;
 pub mod common;
 mod error;
-pub mod library;
 pub mod parser;
 pub mod tags;
 pub mod writer;

crates/typlite/src/library.rs

@@ -1,18 +0,0 @@
-//! # Typlite Library
-
-// scopes.define("link", link as RawFunc);
-// scopes.define("kbd", kbd as RawFunc);
-// scopes.define("md-alter", md_alter as RawFunc);
-// scopes.define("image", image as RawFunc);
-// scopes.define("figure", figure as RawFunc);
-// scopes.define("raw", raw as RawFunc);
-// scopes.define("strike", strike as RawFunc);
-// scopes.define("pad", pad as RawFunc);
-// scopes.define("note-box", note as RawFunc);
-// scopes.define("tip-box", tip as RawFunc);
-// scopes.define("important-box", important_box as RawFunc);
-// scopes.define("warning-box", warning_box as RawFunc);
-// scopes.define("caution-box", caution_box as RawFunc);
-// scopes.define("table", table as RawFunc);
-// scopes.define("grid", grid as RawFunc);
-// pub fn cross_link(mut args: Args) -> typlite::Result<Value>

docs/release-instruction.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/release-instruction.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Release Instructions
 
 Normally, you should always create release candidates to avoid failures in the release process. For example, if you are releasing version `0.12.19`, you should create a release candidate `0.12.19-rc1` first. This is because once you tag a version, you cannot delete it, otherwise the people in downstream that already pull the tag will have to force update their repository. The release candidates are canaries to test any potential poison in the release process. Two things to note:

docs/tinymist/crates/typlite.typ

@@ -1,3 +1,8 @@
+
+#import "/docs/tinymist/frontend/mod.typ": *
+
+#show: book-page.with(title: [Typlite])
+
 #show raw.where(lang: "sh"): it => [#it#metadata(it.text)<shell-script>]
 
 Converts a subset of typst to markdown.

docs/tinymist/frontend/emacs.typ

@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [Emacs])
+#show: book-page.with(title: [Tinymist Emacs Support for Typst])
 
 Run and configure tinymist in Emacs for Typst.
 

docs/tinymist/frontend/helix.typ

@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [Helix])
+#show: book-page.with(title: [Tinymist Helix Support for Typst])
 
 Run and configure tinymist in helix for Typst.
 

docs/tinymist/frontend/neovim.typ

@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [Neovim])
+#show: book-page.with(title: [Tinymist Neovim Support for Typst])
 
 Run and configure `tinymist` in Neovim with support for all major distros and package managers.
 

docs/tinymist/frontend/sublime-text.typ

@@ -1,7 +1,7 @@
 
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [Sublime Support])
+#show: book-page.with(title: [Tinymist Sublime Support for Typst])
 
 Follow the instructions in the #link("https://github.com/sublimelsp/LSP/blob/main/docs/src/language_servers.md#tinymist")[sublimelsp documentation] to make it work.
 

docs/tinymist/frontend/vscode.typ

@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [VS Cod(e,ium)])
+#show: book-page.with(title: [Tinymist Typst VS Code Extension])
 
 A VS Code or VS Codium extension for Typst. You can find the extension on:
 

docs/tinymist/frontend/zed.typ

@@ -1,6 +1,6 @@
 #import "/docs/tinymist/frontend/mod.typ": *
 
-#show: book-page.with(title: [Zed])
+#show: book-page.with(title: [Tinymist Zed Support for Typst])
 
 See #link("https://github.com/WeetHet/typst.zed")[typst.zed];.
 

docs/tinymist/introduction.typ

@@ -2,7 +2,13 @@
 // dist/tinymist/rs
 #import "mod.typ": *
 
-#show: book-page.with(title: "Introduction")
+#let title = if is-md-target {
+  "Tinymist"
+} else {
+  "Introduction"
+}
+
+#show: book-page.with(title: title)
 
 Tinymist [ˈtaɪni mɪst] is an integrated language service for #link("https://typst.app/")[Typst] [taɪpst]. You can also call it "微霭" [wēi ǎi] in Chinese.
 
@@ -62,24 +68,30 @@ See #link("https://myriad-dreamin.github.io/tinymist/")[Online Documentation].
 
 = Packaging
 
+#let channel-img(lnk, img) = if sys-is-html-target {
+  html.elem("a", attrs: (
+    href: lnk,
+    target: "_blank",
+    rel: "noopener noreferrer",
+  ))[
+    #html.elem("img", attrs: (src: img, alt: "Packaging status", style: "max-width: 100%; height: auto;"))
+  ]
+} else {
+  link(lnk)
+}
+
 Stable Channel:
 
-#link(
+#channel-img(
   "https://repology.org/project/tinymist/versions",
-  md-alter(
-    "Packaging status",
-    () => image("https://repology.org/badge/vertical-allrepos/tinymist.svg", alt: "Packaging status"),
-  ),
+  "https://repology.org/badge/vertical-allrepos/tinymist.svg",
 )
 
 Nightly Channel:
 
-#link(
+#channel-img(
   "https://repology.org/project/tinymist-nightly/versions",
-  md-alter(
-    "Packaging status",
-    () => image("https://repology.org/badge/vertical-allrepos/tinymist-nightly.svg", alt: "Packaging status"),
-  ),
+  "https://repology.org/badge/vertical-allrepos/tinymist-nightly.svg",
 )
 
 = Roadmap

docs/tinymist/mod.typ

@@ -24,8 +24,6 @@
 } else {
   raw
 }
-#let md-alter(left, right) = left
-
 #import fletcher.shapes: diamond
 
 #let fg-blue = main-color.mix(rgb("#0074d9"))

editors/emacs/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/emacs.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Emacs Support for Typst
 
 Run and configure tinymist in Emacs for Typst.

editors/helix/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/helix.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Helix Support for Typst
 
 Run and configure tinymist in helix for Typst.

editors/neovim/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/neovim.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Neovim Support for Typst
 
 Run and configure `tinymist` in Neovim with support for all major distros and package managers.

editors/sublime-text/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/sublime-text.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Sublime Support for Typst
 
 Follow the instructions in the [sublimelsp documentation](https://github.com/sublimelsp/LSP/blob/main/docs/src/language_servers.md#tinymist) to make it work.

editors/vscode/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/vscode.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Typst VS Code Extension
 
 A VS Code or VS Codium extension for Typst. You can find the extension on:

editors/zed/README.md

@@ -1,4 +1,4 @@
-<!-- This file is generated by scripts/link-docs.mjs from docs/tinymist/frontend/zed.typ. Do not edit manually. -->
+<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->
 # Tinymist Zed Support for Typst
 
 See [typst.zed](https://github.com/WeetHet/typst.zed).

scripts/link-docs.mjs

@@ -1,20 +1,12 @@
 import { resolve, basename, relative } from "path";
 import * as fs from "fs";
+import * as util from "util";
 import { execSync } from "child_process";
+const exec = util.promisify(execSync);
 
 const root = resolve(import.meta.dirname, "..");
 const dry = process.argv.includes("--dry");
 
-const bytes2utf8 = new TextDecoder();
-
-/**
- * Base64 to UTF-8
- * @param encoded Base64 encoded string
- * @returns UTF-8 string
- */
-export const base64Decode = (encoded) =>
-  bytes2utf8.decode(Uint8Array.from(atob(encoded), (m) => m.charCodeAt(0)));
-
 const yarn = (cmd, stdio = "inherit") => {
   const script = `yarn run ${cmd}`;
   if (dry) {
@@ -32,19 +24,32 @@ const typlite = (input, output) => {
   return res.toString();
 };
 
-const convert = async (inp, out, opts) => {
+const isCheck = process.argv.includes("--check");
+
+const convert = async ({ input: inp, output: out }) => {
   const input = resolve(root, inp);
   const output = resolve(root, out);
-  const { before } = opts || {};
 
-  const res = typlite(input, output).trim();
+  const outputContent = typlite(input, output).trim();
   if (dry) {
-    console.log(res);
+    console.log(outputContent);
     return;
   }
 
-  const outputContent = `<!-- This file is generated by scripts/link-docs.mjs from ${inp}. Do not edit manually. -->\n${before || ""}${res}\n`;
-  await fs.promises.writeFile(output, outputContent);
+  await fs.promises.writeFile(output, outputContent.trim() + "\n");
+
+  if (isCheck) {
+    const gitStatus = (
+      await exec(`git status --porcelain ${output}`, {
+        encoding: "utf-8",
+      })
+    ).trim();
+    if (gitStatus) {
+      throw new Error(
+        `The file ${out} is not up to date. Please run \`node scripts/link-docs.mjs\` locally to update it.`,
+      );
+    }
+  }
 };
 
 // todo: generate me using typlite.
@@ -113,77 +118,45 @@ 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([
-    ...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.`,
-          );
-        }
-      }),
-    );
-  }
-};
+const main = async () => await Promise.all([...tasks.map(convert), maintainerMd()]);
 
 main();

typ/templates/ebook.typ

@@ -16,7 +16,7 @@
   )
 
   // Inherit from gh-pages
-  show: _page-project
+  show: _page-project.with(title: title)
 
   if title != "" {
     set text(size: heading-sizes.at(1))

typ/templates/page.typ

@@ -331,7 +331,7 @@
 /// The project function defines how your document looks.
 /// It takes your content and some metadata and formats it.
 /// Go ahead and customize it to your liking!
-#let project(title: "Tinymist Docs", authors: (), kind: "page", description: none, body) = {
+#let project(title: "", authors: (), kind: "page", description: none, body) = {
   // set basic document metadata
   set document(
     author: authors,
@@ -443,6 +443,15 @@
   if kind == "page" and is-pdf-target and not is-main {
     text(size: 32pt, heading(level: 1, numbering: none, title))
   }
+  if is-md-target {
+    html.elem("m1verbatim", attrs: (
+      src: "<!-- This file is generated by scripts/link-docs.mjs. Do not edit manually. -->\n",
+    ))
+    let title-text = plain-text(title)
+    if title-text.len() > 0 {
+      html.elem("m1verbatim", attrs: (src: "# " + title-text + "\n"))
+    }
+  }
 
   // Main body.
   set par(justify: true)