feat: 在页面底部添加“另请参见”

.github/workflows/build.yml

@@ -46,6 +46,9 @@ jobs:
       - run: pnpm install
 
       - run: pnpm build
+        env:
+          GH_TOKEN: ${{ github.token }} # `<SeeAlso>` requires GitHub API
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.github/workflows/check.yml

@@ -45,6 +45,8 @@ jobs:
       - run: pnpm install
 
       - run: pnpm build
+        env:
+          GH_TOKEN: ${{ github.token }} # `<SeeAlso>` requires GitHub API
 
       - uses: actions/upload-artifact@v4
         with:

README.md

@@ -18,6 +18,9 @@
 可选步骤：
 
 - 如想完全复现例子，可参考[`download-fonts.sh`](./scripts/download-fonts.sh)。
+
 - 如想编译网站中的零星旧例子，可下载 [Typst v0.13.1](https://github.com/typst/typst/releases/tag/v0.13.1)，将可执行文件重命名为`typst-0.13.1`或`typst-0.13.1.exe`，放到`$PATH`上。
 
+- 如想在“另请参见”`<SeeAlso>`一栏解析 GitHub 链接的标题，请设置`$GITHUB_TOKEN`（仅用于访问 GitHub GraphQL API，故无需任何特殊权限；）。
+
 编译的 Typst 例子有缓存。如需清除，可删除`./docs/generated/`目录。

docs/.vitepress/config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vitepress';
 import footnote from 'markdown-it-footnote';
 import UnoCSS from 'unocss/vite';
+import { MarkdownTransform } from './plugins/markdown_transform';
 import TypstRender from './typst_render';
 
 // https://vitepress.dev/reference/site-config
@@ -120,6 +121,6 @@ gtag('config', 'G-NL1RYQ4PW7');`,
   },
 
   vite: {
-    plugins: [UnoCSS()],
+    plugins: [UnoCSS(), MarkdownTransform()],
   },
 });

docs/.vitepress/plugins/markdown_transform.ts

@@ -0,0 +1,33 @@
+import { normalizePath, type Plugin } from 'vite';
+
+/**
+ * A Vite plugin that transforms append contents to markdown sources.
+ *
+ * Inspired by Zotero Chinese, licensed under MIT.
+ * https://github.com/zotero-chinese/website/blob/138ce84ceb8f31b8457babe9119f8e3d35363ed7/src/.vitepress/plugins/markdownTransform.ts
+ */
+export function MarkdownTransform(): Plugin {
+  return {
+    name: 'zhtyp-guide-markdown-transform',
+    enforce: 'pre',
+    async transform(src: string, id: string): Promise<string | null> {
+      const filepath: string = normalizePath(id);
+
+      const faqPattern = /\/FAQ\/[^.]+\.md$/;
+      if (!faqPattern.test(filepath)) {
+        return null;
+      }
+
+      // There is no layout slot in VitePress's default theme that can add contents within `<main>`.
+      // As a result, we have to transform the markdown source.
+      src += `
+<script setup>
+import SeeAlso from "@theme/SeeAlso.vue"
+</script>
+<SeeAlso />
+`;
+
+      return src;
+    },
+  };
+}

docs/.vitepress/theme/SeeAlso.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import { useData, useRoute } from 'vitepress';
+import { computed } from 'vue';
+import { removePrefix } from '../util';
+import { data, type Link, type RelativePath } from './see_also.data';
+
+const route = useRoute();
+const { site } = useData();
+
+/**
+ * Fix the path for Netlify.
+ *
+ * Netlify 部署 URL 比较奇怪：
+ * - 若先访问 /FAQ.html，再单击跳转到 /FAQ/bib-etal-lang.html，则`path === "/FAQ/bib-etal-lang.html"`，正常。
+ * - 若直接访问 /FAQ/bib-etal-lang.html，则`path === "/faq/bib-etal-lang.html"`，变成小写。
+ */
+function fixNetlify(path: RelativePath): RelativePath {
+  return path.replace('/faq/', '/FAQ/') as RelativePath;
+}
+
+const links = computed<Link[] | null>(() => {
+  const path: RelativePath = `/${removePrefix(route.path, site.value.base)}`;
+  return data.linksIndex[path] ?? data.linksIndex[fixNetlify(path)] ?? null;
+});
+</script>
+<template>
+  <section v-if="links">
+    <h2>另请参见</h2>
+    <ul>
+      <li v-for="{ url, title } in links">
+        <a :href="url" target="_blank">{{ title }}</a>
+      </li>
+    </ul>
+  </section>
+</template>

docs/.vitepress/theme/see_also.data.ts

@@ -0,0 +1,59 @@
+/**
+ * Generate data for `<SeeAlso>`.
+ *
+ * # Data sources
+ *
+ * - the index for clreq-gap for typst
+ * - `links: (string | { url: string, title?: string })[]` in page frontmatter
+ *
+ * # Implementation details
+ *
+ * When modifying the page frontmatter, the loader may be called repeatedly. Therefore, network requests are cached.
+ *
+ * For maximal compatibility, features requires network or GitHub API are disabled granularly if not available.
+ *
+ * @module
+ */
+
+import { createContentLoader } from 'vitepress';
+import { resolveAutoTitle } from './see_also_data/auto_title';
+import { parseFrontmatter } from './see_also_data/frontmatter';
+import { fetchGapIndex, parseGapIndex } from './see_also_data/gap_index';
+
+export type Link = {
+  url: string;
+  title: string;
+};
+
+/** The route URL path relative to the site base, e.g., `/FAQ/cite-flying.html`. */
+export type RelativePath = `/${string}`;
+
+export interface Data {
+  linksIndex: Record<RelativePath, Link[]>;
+}
+
+declare const data: Data;
+export { data };
+
+export default createContentLoader('FAQ/*.md', {
+  async transform(rawData): Promise<Data> {
+    const linksIndex: Record<RelativePath, Link[]> = {};
+
+    // Build the links index from data sources
+    for (const data of [
+      parseGapIndex(await fetchGapIndex()),
+      parseFrontmatter(rawData),
+    ]) {
+      for (const [path, links] of data) {
+        if (!linksIndex[path]) {
+          linksIndex[path] = [];
+        }
+        linksIndex[path].push(...links);
+      }
+    }
+
+    await resolveAutoTitle(linksIndex);
+
+    return { linksIndex };
+  },
+});