在页面历史中插入 Typst 历史版本

docs/.vitepress/config.ts

@@ -5,9 +5,14 @@ import {
 import footnote from 'markdown-it-footnote';
 import UnoCSS from 'unocss/vite';
 import { defineConfig } from 'vitepress';
+import {
+  GitChangelog,
+  GitChangelogMarkdownSection,
+} from '@nolebase/vitepress-plugin-git-changelog/vite';
 
 import { PROFILE } from './config_profile';
 import { MarkdownTransform } from './plugins/markdown_transform';
+import { TypstTagsForNolebase } from './plugins/typst_version_nolebase';
 import mirror_link from './plugins/mirror_link';
 import TypstRender from './typst_render';
 
@@ -199,6 +204,14 @@ if (
   },
 
   vite: {
-    plugins: [UnoCSS(), MarkdownTransform()],
+    plugins: [
+      UnoCSS(),
+      MarkdownTransform(),
+      TypstTagsForNolebase(),
+      GitChangelog({
+        repoURL: () => 'https://github.com/typst-doc-cn/guide',
+      }),
+      GitChangelogMarkdownSection(),
+    ],
   },
 });

docs/.vitepress/plugins/typst_version_nolebase.ts

@@ -0,0 +1,25 @@
+import type { Plugin } from 'vite';
+
+import { TYPST_TAGS_FOR_NOLEBASE } from '../theme/typst_version';
+
+export function TypstTagsForNolebase(): Plugin {
+  const name = 'zhtyp-guide-typst-version';
+  const virtualModuleId = `virtual:${name}`;
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+
+  return {
+    name,
+    resolveId(id: string) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    load(id: string) {
+      if (id !== resolvedVirtualModuleId) {
+        return;
+      }
+
+      return `export default ${JSON.stringify(TYPST_TAGS_FOR_NOLEBASE)};`;
+    },
+  };
+}

docs/.vitepress/theme/SeeAlso.vue

@@ -25,7 +25,7 @@ const links = computed<Link[] | null>(() => {
 </script>
 <template>
   <section v-if="links">
-    <h2>另请参见</h2>
+    <h2 id="see-also">另请参见</h2>
     <ul>
       <li v-for="{ url, title } in links">
         <a :href="url" target="_blank">{{ title }}</a>

docs/.vitepress/theme/index.ts

@@ -1,9 +1,14 @@
 import type { Theme } from 'vitepress';
 import DefaultTheme from 'vitepress/theme';
+
+import { NolebaseGitChangelogPlugin } from '@nolebase/vitepress-plugin-git-changelog/client';
+import '@nolebase/vitepress-plugin-git-changelog/client/style.css';
+
+import 'virtual:uno.css';
+
 import Layout from './Layout.vue';
 import FAQList from './FAQList.vue';
 import './custom.css';
-import 'virtual:uno.css';
 
 export default {
   extends: DefaultTheme,
@@ -13,5 +18,6 @@ export default {
   enhanceApp({ app }) {
     // register your custom global components
     app.component('FAQList', FAQList);
+    app.use(NolebaseGitChangelogPlugin);
   },
 } satisfies Theme;

docs/.vitepress/theme/typst_version.ts

@@ -56,3 +56,16 @@ export function getTypstVersion(date: Date): TypstVersion {
     latest: found.tagName == typst_history[0].tagName,
   };
 }
+
+/** Typst tags exported for @nolebase/vitepress-plugin-git-changelog */
+export const TYPST_TAGS_FOR_NOLEBASE = typst_history.map(
+  ({ publishedAt, tagName }) => {
+    const tag = `Typst ${tagName}`;
+    const changelog = `https://typst.app/docs/changelog/${tagName.replace(/^v/, '')}/`;
+    return {
+      date_timestamp: publishedAt.getTime(),
+      tag,
+      release_tag_url: changelog,
+    };
+  },
+);

docs/dev/faq-list.md

@@ -8,7 +8,7 @@ outline: [2, 3]
 
 ## 使用方法
 
-在`/FAQ/*.md`页面正常填写标题，并在 frontmatter 的`tags`字段标注标签。示例请查看[常见问题板块 → 模板与编辑提示](./index.md#模板与编辑提示)。
+在`/FAQ/*.md`页面正常填写标题，并在 frontmatter 的`tags`字段标注标签。示例请查看[常见问题版块 → 模板与编辑提示](./index.md#模板与编辑提示)。
 
 ## 前提条件
 

docs/dev/see-also.md

@@ -35,3 +35,7 @@ links:
 缓存存储在项目中的`/target/cache/`。
 
 允许整体删除缓存文件夹，也允许删除单个文件。
+
+### 计入目录
+
+VitePress 会把[带有`id`的`<h2>`](https://github.com/vuejs/vitepress/blob/ee028266a8fee777a8ee247b1c4490432c0a830e/src/client/theme-default/composables/outline.ts#L24-L29)计入页面右侧的目录。因此，标注`id="see-also"`即可。

docs/dev/typst-render.md

@@ -8,7 +8,7 @@ outline: [2, 3]
 
 ## 使用方法
 
-请移步[常见问题板块 → 模板与编辑提示](./index.md#模板与编辑提示)。
+请移步[常见问题版块 → 模板与编辑提示](./index.md#模板与编辑提示)。
 
 ## 前提条件
 

docs/dev/typst-version.md

@@ -2,9 +2,9 @@
 outline: [2, 3]
 ---
 
-# 更新时针对的 Typst 版本
+# 标注 Typst 版本
 
-将 git 历史与 Typst 版本发布记录比较，在每页`<Layout>`页脚标注更新时针对的 Typst 版本。
+将 git 历史与 Typst 版本发布记录比较，在每页 [Git-based page histories | Nólëbase Integrations](https://nolebase-integrations.ayaka.io/pages/en/integrations/vitepress-plugin-git-changelog/) 中插入 Typst 历史版本，并在`<Layout>`页脚标注最后更新时针对的 Typst 版本。
 
 ## 使用方法
 
@@ -19,3 +19,7 @@ outline: [2, 3]
 ### 版本发布记录
 
 为避免依赖 GitHub API，每次 Typst 发布新版本后，需要手动更新。更新方法见`typst_version.ts`。
+
+### 适配 Nólëbase
+
+通过 vite 扩展`TypstTagsForNolebase`创建[虚拟模块](https://vite.dev/guide/api-plugin#virtual-modules-convention)`virtual:zhtyp-guide-typst-version`，然后通过`pnpm patch @nolebase/vitepress-plugin-git-changelog`读取该模块并定制展示方式。

package.json

@@ -9,30 +9,34 @@
     "fmt": "prettier . --write"
   },
   "devDependencies": {
-    "@shikijs/transformers": "^4.0.2",
-    "@std/fmt": "jsr:^1.0.9",
+    "@nolebase/vitepress-plugin-git-changelog": "^2.18.2",
+    "@shikijs/transformers": "^4.2.0",
+    "@std/fmt": "jsr:^1.0.10",
     "@types/markdown-it": "^14.1.2",
     "@types/markdown-it-footnote": "^3.0.4",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.9.4",
     "@types/which": "^3.0.4",
-    "@waline/client": "^3.13.0",
-    "es-toolkit": "^1.45.1",
-    "prettier": "^3.8.1",
-    "unocss": "^66.6.7",
-    "vite": "^8.0.6",
+    "@waline/client": "^3.15.2",
+    "es-toolkit": "^1.47.1",
+    "prettier": "^3.8.4",
+    "unocss": "^66.7.2",
+    "vite": "^8.0.16",
     "vitepress": "2.0.0-alpha.17",
-    "vue": "^3.5.32",
+    "vue": "^3.5.38",
     "which": "^6.0.1"
   },
   "pnpm": {
     "peerDependencyRules": {
       "ignoreMissing": [
         "@algolia/client-search"
       ]
+    },
+    "patchedDependencies": {
+      "@nolebase/vitepress-plugin-git-changelog": "patches/@nolebase__vitepress-plugin-git-changelog.patch"
     }
   },
   "dependencies": {
-    "markdown-it": "^14.1.1",
+    "markdown-it": "^14.2.0",
     "markdown-it-footnote": "^4.0.0"
   },
   "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977"

patches/@nolebase__vitepress-plugin-git-changelog.patch

@@ -0,0 +1,47 @@
+diff --git a/dist/client/composables/changelog.mjs b/dist/client/composables/changelog.mjs
+index f63b201c453809ad5a5797360ce3f55a70ee6581..cadb0547b88485f5a71bafbc79e1da480a5d9da5 100644
+--- a/dist/client/composables/changelog.mjs
++++ b/dist/client/composables/changelog.mjs
+@@ -2,6 +2,20 @@ import changelog from "virtual:nolebase-git-changelog";
+ import { useData } from "vitepress";
+ import { computed, ref, toValue } from "vue";
+ import { isStringArray } from "../utils.mjs";
++
++import TYPST_TAGS_FOR_NOLEBASE from "virtual:zhtyp-guide-typst-version"
++
++const TYPST_FAKE_COMMITS = TYPST_TAGS_FOR_NOLEBASE.map((
++  { date_timestamp, tag, release_tag_url },
++) => ({
++  date_timestamp,
++  authors: [],
++  tag,
++  tags: [tag],
++  release_tag_url,
++  release_tags_url: [release_tag_url],
++}));
++
+ export function useChangelog() {
+   const { page } = useData();
+   const gitChangelog = ref(changelog);
+@@ -10,10 +24,17 @@ export function useChangelog() {
+   const _commits = computed(() => {
+     const currentPath = toValue(page.value.filePath);
+     const allCommits = gitChangelog.value.commits;
+-    const commits2 = allCommits.filter((c) => c.paths.includes(currentPath)) || [];
+-    return commits2.sort((a, b) => b.date_timestamp - a.date_timestamp).filter((commit, index) => {
+-      if (commit.tag && (!commits2[index + 1] || commits2[index + 1]?.tag))
+-        return false;
++    const commits2 = TYPST_FAKE_COMMITS.concat(allCommits.filter((c) => c.paths.includes(currentPath)) || []);
++    return commits2.sort((a, b) => b.date_timestamp - a.date_timestamp).filter((commit, index, arr) => {
++      // Drop irrelevant tags
++      if (commit.tag) {
++        // `prev` & `next` are in the sense of time, not the position in the array
++        const next = arr[index - 1];
++        const prev = arr[index + 1];
++        // Keep a tag if and only if it's adjacent to a regular commit.
++        return (next && !next.tag) || (prev && !prev.tag);
++      }
++      // Keep all regular commits
+       return true;
+     });
+   });