Markdwon adds metadata, document navigation supports Chinese and English switching

Yesifan · Yesifan · commit 98e7a6466d25 · 2025-01-13T11:30:54.000+08:00
diff --git a/darkit/core/web/.gitignore b/darkit/core/web/.gitignore
@@ -1,6 +1,7 @@
 static/docs/*
 src/routes/docs/**/*.md
 src/routes/docs/navigation.json
+src/routes/docs/navigation_zh.json
 
 # ---- Svelte ----
 node_modules
diff --git a/darkit/core/web/package.json b/darkit/core/web/package.json
@@ -52,6 +52,7 @@
 		"@xyflow/svelte": "^0.1.23",
 		"codejar": "^4.2.0",
 		"echarts": "^5.5.1",
+		"front-matter": "^4.0.2",
 		"mode-watcher": "^0.4.1",
 		"prismjs": "^1.29.0",
 		"svelte-sonner": "^0.3.28",
diff --git a/darkit/core/web/pnpm-lock.yaml b/darkit/core/web/pnpm-lock.yaml
diff --git a/darkit/core/web/src/routes/docs/+layout.svelte b/darkit/core/web/src/routes/docs/+layout.svelte
@@ -1,17 +1,24 @@
 <script>
-	import DocsNavbar from '$lib/components/docs-navbar.svelte';
 	import Navigation from './navigation.json';
+	import ZhNavigation from './navigation_zh.json';
+	import { languageTag } from '$lib/paraglide/runtime';
+	import DocsNavbar from '$lib/components/docs-navbar.svelte';
 
 	let { children } = $props();
 
-	const docsContents = Navigation.map((item) => {
-		return {
-			caption: item.title,
-			contents: item.children.map((child) => {
-				return [child.title, child.path];
-			})
-		};
-	});
+	const navigation = $derived(languageTag() === 'zh' ? ZhNavigation : Navigation);
+
+	const docsContents = $derived(
+		navigation.map((item) => {
+			return {
+				caption: item.title,
+				contents: item.children.map((child) => {
+					const title = child.metadata.title || child.title;
+					return [title, child.path];
+				})
+			};
+		})
+	);
 </script>
 
 <DocsNavbar contents={docsContents} />
diff --git a/darkit/core/web/vite-plugin-docs.ts b/darkit/core/web/vite-plugin-docs.ts
@@ -1,9 +1,11 @@
 import path from 'path';
 import fs from 'fs/promises';
+import fm from 'front-matter';
 import { watch, type FSWatcher } from 'fs';
 import type { Plugin } from 'vite';
 
 export const DOCS_NAVIGATION = 'navigation.json';
+export const ZH_DOCS_NAVIGATION = 'navigation_zh.json';
 
 const ROOT_PATH = path.join(__dirname, '../../../');
 const ROOT_STATIC_PATH = path.join(ROOT_PATH, 'static/docs');
@@ -18,41 +20,47 @@ type DocsTree =
 			order: number;
 			title: string;
 			path: string;
+			metadata: Record<string, any>;
 	  };
 
 const isPathIn = (a: string, b: string) => {
 	const relative = path.relative(b, a);
 	return !relative.startsWith('..') && !path.isAbsolute(relative);
 };
 
-const createDirectory = async (
+const createNavigation = async (
 	source: string,
 	root: string | undefined = undefined
 ): Promise<DocsTree[]> => {
-	const docsTree = [];
+	const docsTree: DocsTree[] = [];
 
 	const files = await fs.readdir(source, { withFileTypes: true });
 	for (const file of files) {
 		//Generate a navigation from an en document
 		const [order, title] = file.name.split('.');
-		if (!order || !title) continue; // 跳过不符合“序号.标题”格式的文件或目录
+		// 跳过不符合“序号.标题”格式的文件或目录
+		if (!order || !title) continue;
 
 		if (file.isDirectory()) {
 			const root2 = root ? `${root}/${title}` : title;
-			const childrenTree = await createDirectory(path.join(source, file.name), root2);
+			const childrenTree = await createNavigation(path.join(source, file.name), root2);
 			docsTree.push({
 				order: parseInt(order, 10),
 				title: title.replace(/-/g, ' '),
 				children: childrenTree
 			});
 		} else if (file.isFile() && file.name.endsWith('.md')) {
+			const content = await fs.readFile(path.join(source, file.name), 'utf-8');
+			const { attributes } = fm(content);
+
 			const title2 = title.replace('.md', '');
 			// svelte router path
-			const path = root ? `/docs/${root}/${title2}` : `/docs/${title2}`;
+			const urlPath = root ? `/docs/${root}/${title2}` : `/docs/${title2}`;
 			docsTree.push({
 				order: parseInt(order, 10),
 				title: title2.replace(/-/g, ' '),
-				path: path
+				path: urlPath,
+				metadata: attributes as Record<string, any>
 			});
 		}
 	}
@@ -137,7 +145,15 @@ export const docs = ({
 	const sourcePath = path.join(__dirname, source);
 	const targetPath = path.join(__dirname, target);
 	const docStaticPath = path.join(__dirname, staticDir);
-	const menusJSONPath = path.join(targetPath, DOCS_NAVIGATION);
+	const navJSONPath = path.join(targetPath, DOCS_NAVIGATION);
+	const zhNavJSONPath = path.join(targetPath, ZH_DOCS_NAVIGATION);
+
+	const i18nWriteNavigationFile = async () => {
+		const enDocsTree = await createNavigation(path.join(ROOT_PATH, 'docs'));
+		const zhDocsTree = await createNavigation(path.join(ROOT_PATH, 'docs', 'zh'));
+		await fs.writeFile(navJSONPath, JSON.stringify(enDocsTree));
+		await fs.writeFile(zhNavJSONPath, JSON.stringify(zhDocsTree));
+	};
 
 	/** 复制静态文件 */
 	const copyStaticFiles = async (files: [string, string][]) => {
@@ -175,8 +191,6 @@ export const docs = ({
 
 	/** 监听 docs 目录下的文件变化，实时更新 docs 目录 */
 	const buildDocsPage = (source: string, target: string) => {
-		const menusJSONPath = path.join(target, DOCS_NAVIGATION);
-
 		const events = new Set<string>();
 		let timer: NodeJS.Timeout | null = null;
 
@@ -189,8 +203,7 @@ export const docs = ({
 				events.clear();
 				console.debug(`Docs page ${Array.from(cache).join(',')} changed: rebuild...`);
 				// 写入新的文档目录
-				const docsTree = await createDirectory(source);
-				await fs.writeFile(menusJSONPath, JSON.stringify(docsTree));
+				await i18nWriteNavigationFile();
 				cache.forEach(async (filename) => {
 					const sourceFile = path.join(source, filename);
 					if (filename.endsWith('.md')) {
@@ -226,8 +239,7 @@ export const docs = ({
 		async config(config, { command }) {
 			isDev = command === 'serve';
 			// 写入新的文档目录
-			const docsTree = await createDirectory(sourcePath);
-			await fs.writeFile(menusJSONPath, JSON.stringify(docsTree));
+			await i18nWriteNavigationFile();
 			await removeDocsCache(targetPath);
 			await copyDocsPage(sourcePath, targetPath);
 		},
diff --git a/docs/1.Introduction/1.About.md b/docs/1.Introduction/1.About.md
@@ -1,3 +1,9 @@
+---
+title: About
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # About
 DarwinKit is a PyTorch-based NLP toolkit that provides some commonly used NLP models and tools.
 
diff --git a/docs/2.User-guide/1.Installation-guide.md b/docs/2.User-guide/1.Installation-guide.md
@@ -1,3 +1,9 @@
+---
+title: Installation Guide
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # Installation Guide
 
 We recommend using Anaconda as the Python environment manager.
diff --git a/docs/2.User-guide/2.How-use-web.md b/docs/2.User-guide/2.How-use-web.md
@@ -1,3 +1,9 @@
+---
+title: How Use Web
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # WEB Tool
 
 DarwinKit also provides a WEB tool to facilitate users to use DarwinKit more conveniently. The web tool is built into DarwinKit, and users can start the WEB service by running the `darkit start` command.
diff --git a/docs/2.User-guide/3.How-use-cli.md b/docs/2.User-guide/3.How-use-cli.md
@@ -1,3 +1,9 @@
+---
+title: How Use CLI
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # CLI Tool
 
 `DarwinKit` provides a CLI tool to facilitate easier usage of `DarwinKit`.
diff --git a/docs/2.User-guide/4.How-use-model.md b/docs/2.User-guide/4.How-use-model.md
@@ -1,3 +1,9 @@
+---
+title: How Use Model
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # Training and using models
 This tutorial will introduce how to use SpikeGPT to train a text generation model and use the trained model to generate text.
 
diff --git a/docs/2.User-guide/5.How-integrated.md b/docs/2.User-guide/5.How-integrated.md
@@ -1,3 +1,9 @@
+---
+title: How Integrated
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # How to integrate models
 DarwinKit supports other models by integrating DarwinKit's interface to use DarwinKit's features. Below is a simple example demonstrating how to integrate a simple model.
 
diff --git a/docs/3.Examples/1.Simple-example.md b/docs/3.Examples/1.Simple-example.md
@@ -1,3 +1,9 @@
+---
+title: Simple Example
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # Simple Example
 
 This is a simple example to show how to use `Trainer` and `Predicter` to train and predict a model.
diff --git a/docs/zh/1.Introduction/1.About.md b/docs/zh/1.Introduction/1.About.md
@@ -1,3 +1,9 @@
+---
+title: 关于 DarwinKit
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # 关于
 该仓库是一个基于 PyTorch 的自然语言处理工具包，提供了一些常用的 NLP 模型和工具。
 
diff --git a/docs/zh/2.User-guide/1.Installation-guide.md b/docs/zh/2.User-guide/1.Installation-guide.md
@@ -1,3 +1,9 @@
+---
+title: 安装指南
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # 安装
 
 我们建议使用 Anaconda 作为 Python 环境管理器。
diff --git a/docs/zh/2.User-guide/2.How-use-web.md b/docs/zh/2.User-guide/2.How-use-web.md
@@ -1,3 +1,9 @@
+---
+title: WEB 工具
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # WEB 工具
 
 DarwinKit 还提供了一个 WEB 网页工具，以便于用户更方便地使用 DarwinKit。网页工具内置于 DarwinKit 中，用户可以通过 `darkit start` 命令启动 WEB 服务。
diff --git a/docs/zh/2.User-guide/3.How-use-cli.md b/docs/zh/2.User-guide/3.How-use-cli.md
@@ -1,3 +1,9 @@
+---
+title: CLI 工具
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # CLI 工具
 
 `DarwinKit` 提供了 CLI 工具，以便于用户更方便地使用 `DarwinKit` 。
diff --git a/docs/zh/2.User-guide/4.How-use-model.md b/docs/zh/2.User-guide/4.How-use-model.md
@@ -1,3 +1,9 @@
+---
+title: 训练和使用模型
+authors:
+  - "Yesifan@yesifan66@zju.edu.cn"
+updated: "2025-01-13"
+---
 # 训练和使用模型
 本教程将介绍如何使用 SpikeGPT 训练一个文本生成模型，并使用训练好的模型生成文本。
 
diff --git a/docs/zh/2.User-guide/5.How-integrated.md b/docs/zh/2.User-guide/5.How-integrated.md
diff --git a/docs/zh/3.Examples/1.Simple-example.md b/docs/zh/3.Examples/1.Simple-example.md
