docs: migration from VuePress to VitePress

Author: fankes

.github/workflows/docs-deploy.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 22
       - name: Prepare Java 21
         uses: actions/setup-java@v4
         with:
@@ -43,7 +43,7 @@ jobs:
           key: gradle-deps-core-${{ hashFiles('**/build.gradle.kts') }}
           restore-keys: |
             gradle-deps
-      - name: Build VuePress site
+      - name: Build VitePress site
         run: |
           cd docs-source
           yarn -i

docs-source/.gitignore

@@ -1,4 +1,3 @@
 /node_modules
-/src/.vuepress/.cache
-/src/.vuepress/.temp
+/src/.vitepress/cache
 /dist

docs-source/build-dokka.sh

@@ -1,17 +1,23 @@
 {
   "name": "pangutext_docs",
   "license": "Apache-2.0",
+  "type": "module",
   "devDependencies": {
-    "@mr-hope/vuepress-plugin-copy-code": "^1.30.0",
-    "@vuepress/plugin-prismjs": "2.0.0-rc.0",
-    "@vuepress/plugin-search": "2.0.0-rc.0",
-    "@vuepress/plugin-shiki": "2.0.0-rc.0",
-    "vuepress": "2.0.0-rc.0"
+    "@mdit-vue/shared": "^2.1.3",
+    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.18.2",
+    "@nolebase/vitepress-plugin-git-changelog": "^2.18.2",
+    "@types/markdown-it": "14.1.2",
+    "@types/node": "^22.0.0",
+    "markdown-it": "^14.1.0",
+    "sass": "^1.89.2",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-comment-with-giscus": "^1.1.15",
+    "vue": "^3.5.33"
   },
   "scripts": {
-    "docs:dev": "vuepress dev src",
-    "docs:build": "vuepress build src",
-    "docs:build-gh-pages": "vuepress build src && touch dist/.nojekyll && sh build-dokka.sh"
-  },
-  "dependencies": {}
+    "docs:dev": "vitepress dev src --host 0.0.0.0",
+    "docs:build": "vitepress build src",
+    "docs:preview": "vitepress preview src --host 0.0.0.0",
+    "docs:build-gh-pages": "vitepress build src && touch dist/.nojekyll && sh build-dokka.sh"
+  }
 }

docs-source/package.json

@@ -0,0 +1,115 @@
+import {
+    GitChangelog,
+    GitChangelogMarkdownSection
+} from '@nolebase/vitepress-plugin-git-changelog/vite';
+import { defineConfig } from 'vitepress';
+import { alignI18nAnchors } from './configs/anchors';
+import { createHomepageAlternates, createRootLocaleRedirect } from './configs/i18n';
+import { configs, pageLinkRefs } from './configs/template';
+import { env, markdown } from './configs/utils';
+import locales from './locales';
+
+export default defineConfig({
+    base: configs.website.base,
+    title: configs.website.title,
+    description: configs.website.locales.en.description,
+    outDir: configs.dev.dest,
+    cacheDir: '.vitepress/cache',
+    vite: {
+        css: {
+            preprocessorOptions: {
+                scss: {
+                    // Vite 5 defaults to Sass's legacy JS API, which Sass 2 will remove.
+                    api: 'modern-compiler'
+                }
+            }
+        },
+        optimizeDeps: {
+            exclude: [
+                '@nolebase/vitepress-plugin-enhanced-readabilities/client',
+                '@nolebase/ui',
+                'vitepress'
+            ]
+        },
+        server: {
+            port: configs.dev.port
+        },
+        plugins: [
+            GitChangelog({
+                repoURL: () => configs.github.repo
+            }),
+            GitChangelogMarkdownSection({
+                excludes: [
+                    'index.md',
+                    'en/index.md',
+                    'zh-cn/index.md'
+                ],
+                sections: {
+                    disableContributors: true
+                }
+            })
+        ],
+        ssr: {
+            noExternal: [
+                '@nolebase/vitepress-plugin-enhanced-readabilities',
+                '@nolebase/ui'
+            ]
+        }
+    },
+    head: [
+        ['meta', { name: 'color-scheme', content: 'light dark' }],
+        ['link', { rel: 'icon', href: configs.website.icon }]
+    ],
+    transformHead: ({ page }) => [
+        ...createHomepageAlternates(page),
+        ...createRootLocaleRedirect(page)
+    ],
+    locales: locales.locales,
+    markdown: {
+        image: {
+            lazyLoading: true
+        },
+        config: (md) => {
+            md.use(alignI18nAnchors);
+            markdown.localizeContainerTitles(md);
+            markdown.injectLinks(md, env.dev ? pageLinkRefs.dev : pageLinkRefs.prod, configs.website.base);
+        }
+    },
+    themeConfig: {
+        logo: configs.website.logo,
+        socialLinks: [{
+            icon: 'github',
+            link: configs.github.repo
+        }],
+        search: {
+            provider: 'local',
+            options: {
+                // VitePress has no isSearchable callback; empty rendered HTML excludes the root redirect page.
+                _render: (src, renderEnv, md) => renderEnv.relativePath === 'index.md' ? '' : md.render(src, renderEnv),
+                locales: {
+                    'zh-cn': {
+                        translations: {
+                            button: {
+                                buttonText: '搜索',
+                                buttonAriaLabel: '搜索'
+                            },
+                            modal: {
+                                noResultsText: '无法找到相关结果',
+                                resetButtonTitle: '清除查询条件',
+                                footer: {
+                                    selectText: '选择',
+                                    navigateText: '切换',
+                                    closeText: '关闭'
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        footer: {
+            message: 'Released under the Apache-2.0 License',
+            copyright: 'Copyright © 2019 HighCapable'
+        }
+    }
+});

docs-source/src/.vitepress/config.ts

@@ -1,9 +1,8 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import MarkdownIt from 'markdown-it';
-import type StateCore from 'markdown-it/lib/rules_core/state_core';
-import type Token from 'markdown-it/lib/token';
 import { slugify } from '@mdit-vue/shared';
+import type { VitePressMarkdownIt } from './types';
 
 interface HeadingAnchor {
     alignedId: string;
@@ -21,10 +20,19 @@ interface CachedHeadingLookup {
     mtimeMs: number;
 }
 
+interface MarkdownToken {
+    children: MarkdownToken[] | null;
+    content: string;
+    tag: string;
+    type: string;
+    attrGet: (name: string) => string | null;
+    attrSet: (name: string, value: string) => void;
+}
+
 interface HeadingToken {
-    inlineToken: Token;
+    inlineToken: MarkdownToken;
     pathKey: string;
-    token: Token;
+    token: MarkdownToken;
 }
 
 interface LinkResolveContext {
@@ -52,9 +60,9 @@ const createHeadingPathTracker = (): ((level: number) => string) => {
     };
 };
 
-const getHeadingLevel = (token: Token): number => Number.parseInt(token.tag.slice(1), 10);
+const getHeadingLevel = (token: MarkdownToken): number => Number.parseInt(token.tag.slice(1), 10);
 
-const getHeadingText = (inlineToken: Token): string =>
+const getHeadingText = (inlineToken: MarkdownToken): string =>
     (inlineToken.children ?? [])
         .filter((child) => child.type === 'text' || child.type === 'code_inline')
         .map((child) => child.content)
@@ -72,7 +80,7 @@ const createUniqueSlug = (candidate: string, usedSlugs: Set<string>): string =>
     return resolvedSlug;
 };
 
-const collectHeadings = (tokens: Token[]): HeadingAnchor[] => {
+const collectHeadings = (tokens: MarkdownToken[]): HeadingAnchor[] => {
     const nextPathKey = createHeadingPathTracker();
     const usedSlugs = new Set<string>();
     const headings: HeadingAnchor[] = [];
@@ -165,7 +173,7 @@ const resolveHeadingLookup = (filePathRelative: string | null | undefined): Head
     return lookup;
 };
 
-const collectHeadingTokens = (tokens: Token[]): HeadingToken[] => {
+const collectHeadingTokens = (tokens: MarkdownToken[]): HeadingToken[] => {
     const nextPathKey = createHeadingPathTracker();
     const headings: HeadingToken[] = [];
     for (let index = 0; index < tokens.length; index += 1) {
@@ -186,7 +194,7 @@ const collectHeadingTokens = (tokens: Token[]): HeadingToken[] => {
     return headings;
 };
 
-const syncPermalinkHref = (inlineToken: Token, id: string): void => {
+const syncPermalinkHref = (inlineToken: MarkdownToken, id: string): void => {
     for (const child of inlineToken.children ?? []) {
         if (child.type !== 'link_open') {
             continue;
@@ -218,22 +226,6 @@ const hasUriScheme = (value: string): boolean => /^[a-z][a-z\d+.-]*:/i.test(valu
 const normalizeFilePathRelative = (filePathRelative: string): string =>
     filePathRelative.replace(/\\/g, '/');
 
-const normalizeBase = (base = '/'): string => {
-    const trimmed = base.trim();
-    if (trimmed === '' || trimmed === '/') {
-        return '/';
-    }
-    return `/${trimmed.replace(/^\/+|\/+$/g, '')}/`;
-};
-
-const toSiteRoutePath = (filePathRelative: string, base = '/'): string => {
-    const normalizedFilePath = normalizeFilePathRelative(filePathRelative);
-    const routePath = normalizedFilePath.endsWith('/index.md')
-        ? normalizedFilePath.slice(0, -'index.md'.length)
-        : normalizedFilePath.replace(/\.md$/, '.html');
-    return `${normalizeBase(base)}${routePath}`.replace(/\/{2,}/g, '/');
-};
-
 const resolveTargetFilePathRelative = (currentFilePathRelative: string, rawPath: string, base = '/'): string | null => {
     const normalizedCurrentPath = normalizeFilePathRelative(currentFilePathRelative);
     if (rawPath.length === 0) {
@@ -264,9 +256,10 @@ const resolveTargetFilePathRelative = (currentFilePathRelative: string, rawPath:
     return `${path.posix.join(path.posix.dirname(normalizedCurrentPath), rawPath)}.md`;
 };
 
-export const alignI18nAnchors = (md: MarkdownIt): void => {
-    md.core.ruler.after('anchor', 'align-i18n-anchors', (state: StateCore) => {
-        const lookup = resolveHeadingLookup(state.env.filePathRelative);
+/** Aligns localized heading IDs with the matching English document structure. */
+export const alignI18nAnchors = (md: VitePressMarkdownIt): void => {
+    md.core.ruler.after('anchor', 'align-i18n-anchors', (state) => {
+        const lookup = resolveHeadingLookup(state.env.relativePath);
         if (!lookup) {
             return;
         }
@@ -285,6 +278,7 @@ export const alignI18nAnchors = (md: MarkdownIt): void => {
     });
 };
 
+/** Rewrites localized heading fragments while preserving VitePress source-relative paths. */
 export const resolveI18nLink = (context: LinkResolveContext, rawHref: string): string => {
     if (!context.filePathRelative || !rawHref.includes('#')) {
         return rawHref;
@@ -308,5 +302,5 @@ export const resolveI18nLink = (context: LinkResolveContext, rawHref: string): s
     if (normalizeFilePathRelative(targetFilePathRelative) === currentFilePathRelative) {
         return `#${resolvedHash}`;
     }
-    return `${toSiteRoutePath(targetFilePathRelative, context.base)}#${resolvedHash}`;
+    return `${rawPath}#${resolvedHash}`;
 };

…-source/src/.vuepress/configs/anchors.ts …source/src/.vitepress/configs/anchors.tsdocs-source/src/.vuepress/configs/anchors.ts renamed to docs-source/src/.vitepress/configs/anchors.ts docs-source/src/.vuepress/configs/anchors.ts renamed to docs-source/src/.vitepress/configs/anchors.ts

@@ -0,0 +1,23 @@
+import type giscusTalk from 'vitepress-plugin-comment-with-giscus';
+
+type GiscusOptions = Parameters<typeof giscusTalk>[0];
+
+/** Lists source pages that must not mount the Giscus comment section. */
+export const giscusExcludedPages = [
+    'en/about/about.md',
+    'zh-cn/about/about.md'
+];
+
+/** Defines the GitHub Discussions repository, category, and localized Giscus behavior. */
+export const giscusOptions = {
+    repo: 'BetterAndroid/PanguText',
+    repoId: 'R_kgDOMRzxbg',
+    category: 'General',
+    categoryId: 'DIC_kwDOMRzxbs4DB_ZV',
+    inputPosition: 'bottom',
+    locales: {
+        'en-US': 'en',
+        'zh-CN': 'zh-CN'
+    },
+    homePageShowComment: false
+} satisfies GiscusOptions;

docs-source/src/.vitepress/configs/giscus.ts

@@ -0,0 +1,48 @@
+import type { HeadConfig } from 'vitepress';
+import { configs } from './template';
+
+export type DocsLocale = keyof typeof configs.website.locales;
+
+const supportedLocales = Object.keys(configs.website.locales) as DocsLocale[];
+const homepagePaths = new Set(['index.md', 'en/index.md', 'zh-cn/index.md']);
+
+/** Locale used when the visitor has not selected a documentation language. */
+export const defaultLocale: DocsLocale = 'en';
+
+/** Storage key used to remember the last documentation locale visited by the user. */
+export const localeStorageKey = 'pangutext-docs-locale';
+
+/** Returns a supported locale when the route belongs to a localized documentation tree. */
+export const resolveRouteLocale = (path: string) => path
+    .split('/')
+    .find((segment): segment is DocsLocale => supportedLocales.includes(segment as DocsLocale));
+
+/** Returns a stored locale when valid, otherwise falling back to English. */
+export const resolveStoredLocale = (locale: string | null) => supportedLocales
+    .find((supportedLocale) => supportedLocale === locale) ?? defaultLocale;
+
+/** Creates reciprocal hreflang links for every localized homepage and the x-default root. */
+export const createHomepageAlternates = (page: string): HeadConfig[] => {
+    if (!homepagePaths.has(page)) return [];
+    const siteRoot = `${configs.github.page}/`;
+    const localeLinks = Object.entries(configs.website.locales).map(([locale, options]) => [
+        'link',
+        {
+            rel: 'alternate',
+            hreflang: options.lang,
+            href: `${siteRoot}${locale}/`
+        }
+    ] satisfies HeadConfig);
+    return [
+        ...localeLinks,
+        ['link', { rel: 'alternate', hreflang: 'x-default', href: siteRoot }]
+    ];
+};
+
+/** Creates the root-page fallback redirect used when static hosting cannot return HTTP 302. */
+export const createRootLocaleRedirect = (page: string): HeadConfig[] => {
+    if (page !== 'index.md') return [];
+    const base = configs.website.base;
+    const script = `(() => { let locale = '${defaultLocale}'; try { const saved = localStorage.getItem('${localeStorageKey}'); if (saved === 'en' || saved === 'zh-cn') locale = saved; } catch {} location.replace('${base}' + locale + '/'); })();`;
+    return [['script', {}, script]];
+};