feat(docs): 添加泛型安全转义插件并增加源代码生成器文档

- 实现 safeGenericEscapePlugin 插件保护 Markdown 中的泛型语法
- 配置 Vite 构建选项提高代码块大小警告阈值至 1000
- 添加 Priority 生成器和 Context Get 注入文档链接
- 重构配置文件结构将插件函数移至顶部定义
- 确保代码块和 HTML 标签在转义过程中得到正确保护
This commit is contained in:
GeWuYou 2026-03-29 20:08:20 +08:00
parent 010ab70b7f
commit 159578ab90

View File

@ -1,5 +1,51 @@
import { defineConfig } from 'vitepress'
function safeGenericEscapePlugin() {
return {
name: 'safe-generic-escape',
enforce: 'pre',
transform(code: string, id: string) {
if (!id.endsWith('.md')) return
const codeBlocks: string[] = []
const htmlBlocks: string[] = []
// 1⃣ 保护代码块 ``` ```
let processed = code.replace(/```[\s\S]*?```/g, (match) => {
const i = codeBlocks.length
codeBlocks.push(match)
return `__CODE_BLOCK_${i}__`
})
// 2⃣ 保护 HTML 标签(避免破坏 Vue SFC
processed = processed.replace(/<\/?[a-zA-Z][^>]*>/g, (match) => {
const i = htmlBlocks.length
htmlBlocks.push(match)
return `__HTML_BLOCK_${i}__`
})
// 3⃣ 只转义"泛型形式"的 <T> 或 <K, V>
processed = processed.replace(
/<([A-Z][A-Za-z0-9_,\s]*)>/g,
(_, inner) => `&lt;${inner}&gt;`
)
// 4⃣ 恢复 HTML
htmlBlocks.forEach((block, i) => {
processed = processed.replace(`__HTML_BLOCK_${i}__`, block)
})
// 5⃣ 恢复代码块
codeBlocks.forEach((block, i) => {
processed = processed.replace(`__CODE_BLOCK_${i}__`, block)
})
return processed
}
}
}
export default defineConfig({
title: 'GFramework',
@ -10,7 +56,11 @@ export default defineConfig({
/** GitHub Pages / 子路径部署 */
base: '/GFramework/',
vite: {
plugins: [safeGenericEscapePlugin()]
plugins: [safeGenericEscapePlugin()],
build: {
// 提高代码块大小警告阈值(文档包含大量代码示例)
chunkSizeWarningLimit: 1000
}
},
/** 多语言 */
locales: {
@ -162,7 +212,9 @@ export default defineConfig({
{ text: '概览', link: '/zh-CN/source-generators/' },
{ text: '日志生成器', link: '/zh-CN/source-generators/logging-generator' },
{ text: '枚举扩展', link: '/zh-CN/source-generators/enum-generator' },
{ text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' }
{ text: 'ContextAware 生成器', link: '/zh-CN/source-generators/context-aware-generator' },
{ text: 'Priority 生成器', link: '/zh-CN/source-generators/priority-generator' },
{ text: 'Context Get 注入', link: '/zh-CN/source-generators/context-get-generator' }
]
}
],
@ -251,50 +303,3 @@ export default defineConfig({
}
}
})
import { defineConfig } from 'vitepress'
function safeGenericEscapePlugin() {
return {
name: 'safe-generic-escape',
enforce: 'pre',
transform(code: string, id: string) {
if (!id.endsWith('.md')) return
const codeBlocks: string[] = []
const htmlBlocks: string[] = []
// 1⃣ 保护代码块 ``` ```
let processed = code.replace(/```[\s\S]*?```/g, (match) => {
const i = codeBlocks.length
codeBlocks.push(match)
return `__CODE_BLOCK_${i}__`
})
// 2⃣ 保护 HTML 标签(避免破坏 Vue SFC
processed = processed.replace(/<\/?[a-zA-Z][^>]*>/g, (match) => {
const i = htmlBlocks.length
htmlBlocks.push(match)
return `__HTML_BLOCK_${i}__`
})
// 3⃣ 只转义“泛型形式”的 <T> 或 <K, V>
processed = processed.replace(
/<([A-Z][A-Za-z0-9_,\s]*)>/g,
(_, inner) => `&lt;${inner}&gt;`
)
// 4⃣ 恢复 HTML
htmlBlocks.forEach((block, i) => {
processed = processed.replace(`__HTML_BLOCK_${i}__`, block)
})
// 5⃣ 恢复代码块
codeBlocks.forEach((block, i) => {
processed = processed.replace(`__CODE_BLOCK_${i}__`, block)
})
return processed
}
}
}