快速开始
1. 替换域名
打开 config.mts 文件,将 'sitemap' 和 'socialLinks' 部分更改为您自己的域名。
{
sitemap: {
hostname: "https://docs.code2life.top",
hostname: "https://docs.awesome.com",
},
socialLinks: [
{
icon: "github",
link: "https://github.com/code2life/vitepress-diataxis-template",
link: "https://github.com/your-org/your-project",
},
]
}
2. 设置 Giscus 评论
将 Giscus 应用安装到您的 公共 文档仓库。
启用仓库的讨论功能。
在
docs/.vitepress/theme/components/VComments.vue
中替换data-repo
、data-repo-id
、data-category
和data-category-id
,代码片段可在 Giscus 官网找到。vue// docs/.vitepress/theme/components/VComment.vue <ClientOnly> <component :is="'script'" src="https://giscus.app/client.js" data-repo="replace-me" data-repo-id="replace-me" data-category="General" data-category-id="replace-me" data-mapping="pathname" data-strict="0" :data-theme="isDark ? 'dark' : 'light'" data-reactions-enabled="1" data-emit-metadata="0" crossorigin="anonymous" data-input-position="top" data-lang="en" data-loading="lazy" async /> </ClientOnly>
3. 设置翻译功能
大多数自动翻译效果不佳,您可以使用 Cursor 翻译 Markdown 文件。此仓库为 Cursor 内置了 Prompt 文件,您可以按照以下 3 个步骤开始使用。
- 选择一个文件或部分,点击 Command+K 或 Command+L 打开 Cursor 聊天。
- 输入 @translate-revise,然后按 Enter。
- Cursor 将自动翻译所选文本,您可以审核并保存。
4. 设置 Google 和 PostHog 分析
注册一个 Google Analytics 账户并获取测量 ID(G-XXXXXXXXXX)。
将测量 ID 添加到
docs/.vitepress/config.mts
的 head 部分:jshead: [ ["script", { src: "https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX" }], ["script", {}, `window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX');`], ],
请记得更新 public/robots.txt
以匹配您自己的主机名。
PostHog 是一个出色的 SaaS 产品,几乎涵盖了所有客户行为分析需求。
前往 PostHog,注册账户并按照设置步骤进行,然后复制代码片段以替换 docs/.vitepress/config.mts
的 head 部分。
head: [
["meta", { name: "color-scheme", content: "dark" }],
...
[
"script",
{},
// 从 PostHog 入门页面复制您自己的脚本
`!function(t,e){var o,n,p,r;e.__SV||(window.posthog=...{api_host:'https://us.i.posthog.com'...`,
],
],
5. 设置 Sandpack 代码沙箱
Sandpack 是在文档中添加交互式教程的绝佳工具,特别适用于前端技术栈。这个模板已经开箱即用,详见
参见 示例页面 并查阅 vitepress-plugin-sandpack 文档 了解更多详细信息。
6. 添加自动生成的 API 文档
此模板集成了 Stoplightio Elements ,基于 OpenAPI 模式自动生成 API 文档,建议使用无布局的单独页面。
只需一行文档即可使用 WebComponent,参见 此示例。
---
layout: false
---
<ClientOnly>
<elements-api apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml" router="hash" layout="sidebar"></elements-api>
</ClientOnly>
如果需要自定义 API 文档页面,请查看 Stoplight Elements 选项。
7. 自定义
阅读 VitePress 官方文档以了解自定义方法,以下是一些常见的自定义入口点。
docs/.vitepress/sidebar.mts
用于更改指南/参考的菜单,添加新 Markdown 后记得更新它。docs/.vitepress/en.mts
和docs/.vitepress/zh.mts
是配置整个页面菜单和链接的入口点,根据需求进行调整。- 您可以通过编辑
docs/.vitepress/theme/index.ts
来 更改默认布局。 - 您可以通过添加新组件并在前端格式器中使用它们来 自定义其他布局。
已知问题
- 由于
vitepress-plugin-mermaid
的 bug,Mermaid 饼图和 ZenUML 无法正常工作。 - 页面布局未针对多产品优化。
- 搜索功能默认是本地前端搜索,如果内容很多,建议切换为像 Algolia 这样的远程搜索。