快速开始

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 部分：

head: [
    ["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，参见此示例。

html

---
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 这样的远程搜索。

快速开始 ​

1. 替换域名 ​

2. 设置 Giscus 评论 ​

3. 设置翻译功能 ​

4. 设置 Google 和 PostHog 分析 ​

5. 设置 Sandpack 代码沙箱 ​

6. 添加自动生成的 API 文档 ​

7. 自定义 ​

已知问题 ​