feat: Add pre/next links to /faq/* (#482)

Author: YDX-2147483647

wiki/.vitepress/config.mts

@@ -1,7 +1,9 @@
-import { defineConfig } from 'vitepress'
+import assert from 'node:assert'
+
+import { defineConfig, type DefaultTheme } from 'vitepress'
 import * as footnote from 'markdown-it-footnote'
 
-import { generate_index_tex } from './theme/faq_data'
+import { generate_index_tex, generate_prev_next_links } from './theme/faq_data'
 import LinkRender from './theme/link_render'
 
 export default defineConfig({
@@ -83,6 +85,7 @@ export default defineConfig({
             { text: '将 LaTeX 转换为 Word', link: '/guide/converting-to-word' },
             { text: 'LaTeX 学习与使用资源', link: '/guide/resources' },
             { text: '常用命令', link: '/guide/commands' },
+            // `/faq/`会记于`*.tex`的注释中，需尽量简短，故不前缀`/guide/`；相关影响在`transformPageData`中修复
             { text: '疑难杂症', link: '/faq/' },
           ],
         },
@@ -146,4 +149,24 @@ export default defineConfig({
     }
   },
   buildEnd: generate_index_tex,
+  transformPageData(page, context) {
+    // Add pre/next links to `/faq/*`
+    // https://vitepress.dev/reference/default-theme-prev-next-links
+    if (page.relativePath === 'faq/index.md') {
+      // 确认`sidebar`改得不太多
+      const sidebar = context.siteConfig.userConfig.themeConfig.sidebar['/guide'] as DefaultTheme.SidebarItem[]
+      assert.ok(sidebar)
+      const section = sidebar.at(-2)
+      assert.strictEqual(section?.text, '常见问题')
+      assert.strictEqual(section.items?.at(-1)?.link, '/faq/')
+
+      // Fix pre/next links
+      page.frontmatter.prev ??= section.items.at(-2)
+      page.frontmatter.next ??= sidebar.at(-1)?.items?.at(0)
+    } else if (page.relativePath.startsWith('faq/')) {
+      const { prev, next } = generate_prev_next_links(page)
+      page.frontmatter.prev ??= prev
+      page.frontmatter.next ??= next
+    }
+  },
 })

wiki/.vitepress/theme/faq_data.ts

@@ -6,9 +6,9 @@ import { writeFileSync } from 'node:fs'
 import path from 'node:path'
 
 import matter from 'gray-matter'
-import { createContentLoader, type SiteConfig } from 'vitepress'
+import { createContentLoader, type PageData, type SiteConfig } from 'vitepress'
 
-import { normalizeTag } from './util'
+import { normalizeTag, tagURL } from './util'
 
 export interface FAQItem {
   title: string
@@ -121,3 +121,18 @@ function as_latex_href(title: string, url: string): string {
   ])
   return `\\href{${url}}{${escaped}}`
 }
+
+/**
+ * Generate [prev/next links](https://vitepress.dev/reference/default-theme-prev-next-links).
+ */
+export function generate_prev_next_links(page: PageData): {
+  prev: { text: string; link: string }
+  next?: { text: string; link: string }
+} {
+  const prev = { text: '疑难解答', link: '/faq/' }
+
+  const tag = normalizeTag(page.frontmatter.tag).at(0)
+  const next = tag ? { text: `${tag} 问题目录`, link: tagURL(tag) } : undefined
+
+  return { prev, next }
+}