ContextQMD
Back to Plate

本地文档

docs/installation/docs.cn.mdx

1.0.06.1 KB
Original Source

在本地托管 Plate 文档，将其直接集成到您的项目中。这种设置确保您的团队使用与 Plate 版本匹配的文档，同时使 AI 工具能够更好地理解和协助您的代码库。

为什么要在本地托管文档？

本地文档相比外部网站具有明显优势：

  • 版本锁定： 保持文档与项目的 Plate 版本同步。避免因较新、未采用的 Plate 版本中的功能或 API 而产生混淆。
  • AI 就绪开发：
    • 优于 llms.txt： 虽然将文档转储到单个文本文件中是 LLM 上下文的常见做法，但对于大型文档（超过典型的 100k token 限制）这种方法会失效。我们的结构化本地设置让 AI 工具能够精确访问所需内容。
    • AI 工具直接访问： 您的 AI 辅助 IDE 可以直接访问特定版本的文档，从而为您的 Plate 设置提供准确的代码生成和上下文帮助。
    • 为 AI 任务结构化： AI 工具可以帮助完成翻译文档、创建摘要或在 Plate 版本之间更新文档等任务。
  • 自定义与控制： 修改文档外观和结构以匹配您的项目需求。
  • 轻松更新： 像代码一样处理文档 - 与代码库一起进行审查、更新和版本控制。
  • 快速访问： 获得可靠、快速的文档访问。
  • 中央枢纽： 将 Plate 文档与其他库的文档集中在一处。

设置指南

有两种方式设置本地文档：

方式一：文档应用

此方式使用 Fumadocs 设置完整的文档站点，提供可搜索、可导航的界面。

<Steps>

创建 Fumadocs 应用

设置 Fumadocs 应用，它为您的文档站点提供基于 Next.js 的框架：

bash
pnpm create fumadocs-app

设置过程中：

  • 名称： 提示时输入 docs
  • 选择您偏好的选项（默认选项即可）
  • 向导将创建包含所有必要文件的 docs 目录

进入新创建的 docs 目录：

bash
cd docs

详细的 Fumadocs 设置，请参阅 Fumadocs UI 文档。

创建 components.json

在您的 docs 目录中，创建 components.json 文件。您有两个选项：

选项 A：命令行

bash
echo '{\n  "$schema": "https://ui.shadcn.com/schema.json",\n  "style": "new-york",\n  "rsc": true,\n  "tsx": true,\n  "tailwind": {\n    "config": "",\n    "css": "app/global.css",\n    "baseColor": "neutral",\n    "cssVariables": true,\n    "prefix": ""\n  },\n  "aliases": {\n    "components": "@/components",\n    "utils": "@/lib/utils",\n    "ui": "@/components/ui",\n    "lib": "@/lib",\n    "hooks": "@/hooks"\n  },\n  "iconLibrary": "lucide"\n}' > components.json

选项 B：复制粘贴

在您的 docs 目录中创建名为 components.json 的新文件，内容如下：

json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/global.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

添加 Plate 文档

现在，获取 Plate 文档文件和必要的 MDX 组件。

bash
npx shadcn@latest add @plate/fumadocs
<Callout type="warning" title="特定版本文档"> 上述命令安装的是**最新版本**的 Plate 文档。对于使用旧版 Plate（最低 `v48.0.0`）的项目，请指定您的版本：
  1. 前往 GitHub 上的 Plate 公共注册表。
  2. 使用标签切换器选择您的 Plate 版本。
  3. 复制版本化 URL（例如，v48）。
  4. 将 shadcn 命令中的 https://platejs.org/r/ 替换为此 URL。 </Callout>

运行 Fumadocs 应用

启动开发服务器：

bash
pnpm run dev

您的文档站点将在以下地址可用：

  • Plate 文档：http://localhost:3000/docs/plate

自定义

使用 Fumadocs 功能增强您的文档。

</Steps>

方式二：仅 MDX 文件

如果您只想要文档文件而不设置完整站点，可以直接将它们添加到现有项目中：

bash
# 从项目根目录运行（您想要放置文档的位置）
npx shadcn@latest add @plate/docs

这将：

  • 在您的项目中安装 MDX 文档文件（通常在 docs/ 或类似目录中）
  • 完全跳过 Fumadocs 设置
  • 为您提供原始 MDX 文件，您可以按需使用

使用场景：

  • 直接在代码库中引用文档
  • 与现有文档设置集成
  • 使文档对 AI 工具可用以获得更好的上下文

高级集成

MCP 集成

通过将 Plate 服务器添加到您的 .cursor/mcp.json（或等效文件）中，使 AI 工具能够使用您的本地文档。

json
{
  "mcpServers": {
    "shadcn": {
      "description": "Shadcn and Plate MCP",
      "command": "npx",
      "args": [
        "shadcn@latest",
        "mcp"
      ]
    }
  }
}

您的 AI 工具随后可以：

  • 访问文档上下文以获得更好的代码辅助
  • 帮助管理和更新文档
  • 使用正确的导入和配置生成代码
  • 协助编辑器设置和功能集成

更多详情请参阅 MCP 指南。

<Callout> 配置完成后，尝试询问您的 AI： ```bash "帮我理解 Plate AI 插件是如何工作的" "如何创建自定义插件？" "最新版本的 Plate 有什么新功能？" ``` </Callout>

集中管理多个文档

您的 content/docs/ 目录可以托管多个库的文档。复制 Plate 的流程来添加其他内部或外部工具的文档：

plaintext
content/
└── docs/
    ├── plate/         # Plate 文档
    │   └── ...
    ├── other-library/ # 其他库的文档
    │   └── ...
    └── index.mdx      # 所有文档的主页

这为您的项目技术栈创建了一个统一的、版本控制的知识库。