holocron

Holocron

Holocron 文档更新很快。请勿依赖过时的训练数据或相对于仓库的源路径。请先获取公开文档，再进行搜索。

相关文档页面

获取 https://holocron.so/sitemap.xml 以查看所有可用页面。在任意页面 URL 后添加 .md，即可获取原始 Markdown。每次都必须完整读取输出；切勿将 curl 输出通过 head、tail、sed -n 或任何截断命令传递。

curl -s https://holocron.so/sitemap.xml
curl -s https://holocron.so/docs/quickstart.md

用户询问特定工作流时，请直接获取对应页面：

• 概述：https://holocron.so/llms.txt
• 快速入门：https://holocron.so/docs/quickstart.md
• Holocron 是什么：https://holocron.so/docs/what-is-holocron.md
• 创建页面：https://holocron.so/docs/create/pages.md
• MDX 语法：https://holocron.so/docs/create/mdx.md
• 本地导入：https://holocron.so/docs/create/local-imports.md
• 重定向：https://holocron.so/docs/create/redirects.md
• docs.json 配置：https://holocron.so/docs/organize/docs-json.md
• 配置架构：https://holocron.so/docs.json
• 导航：https://holocron.so/docs/organize/navigation.md
• 主题自定义：https://holocron.so/docs/customize/theme.md
• 图标：https://holocron.so/docs/customize/icons.md
• 自定义入口（Spiceflow）：https://holocron.so/docs/custom-entry.md
• Spiceflow 集成：https://holocron.so/docs/spiceflow.md
• Cloudflare 部署：https://holocron.so/docs/deploy/cloudflare.md
• Node 部署：https://holocron.so/docs/deploy/node.md
• Holocron 部署：https://holocron.so/docs/deploy/holocron.md
• AI 助手文档：https://holocron.so/docs/ai/assistant.md
• Bleed：https://holocron.so/docs/customize/bleed.md
• 布局和页面模式：https://holocron.so/docs/customize/layout.md

curl -fsSL https://holocron.so/docs/quickstart.md
curl -fsSL https://holocron.so/docs/organize/docs-json.md

搭建新项目

使用 CLI，通过可运行的模板创建新的文档站点：

npx -y "@holocron.so/cli" create --name "My Docs" my-docs --skip-auth

--skip-auth 标志会跳过云端设置和 AI 聊天设置（适合 Agent 和仅限本地的使用场景）。模板包含 vite.config.ts、docs.jsonc、示例页面，以及带标签页、锚点和图标的导航。

搭建完成后，启动开发服务器：

cd my-docs
pnpm install
pnpm dev

docs.json 基础知识

Holocron 会读取 docs.json、docs.jsonc 或 holocron.jsonc。手动编写时，优先使用 docs.jsonc，因为注释和尾随逗号能让配置更易于维护。

添加不常见的配置字段前，务必先获取架构：

curl -fsSL https://holocron.so/docs.json

简单的 docs.jsonc：

{
  "$schema": "https://holocron.so/docs.json",
  "name": "Acme",
  "description": "Documentation for Acme.",
  "colors": { "primary": "#6366f1" },
  "icons": { "library": "lucide" },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "icon": "lucide:rocket",
        "pages": ["index", "docs/quickstart"]
      },
      {
        "group": "Guides",
        "icon": "lucide:map",
        "pages": ["docs/install", "docs/deploy"]
      }
    ],
    "global": {
      "anchors": [
        { "anchor": "GitHub", "href": "https://github.com/example/docs", "icon": "lucide:github" },
        { "anchor": "Changelog", "href": "https://github.com/example/docs/releases", "icon": "lucide:newspaper" }
      ]
    }
  }
}

navigation.pages 中的页面 slug 会映射到 MDX 文件。docs/quickstart 会加载 docs/quickstart.mdx，而 docs/install 会加载 docs/install.mdx。

导航栏链接和 CTA

登录、仪表板、注册等应用路由应添加到 navbar 和 knownPaths 中，以通过链接检查：

"navbar": {
  "links": [{ "label": "Log in", "href": "/login" }, { "label": "Dashboard", "href": "/dashboard" }],
  "primary": { "type": "button", "label": "Start free trial", "href": "/signup" }
},
"knownPaths": ["/login", "/signup", "/dashboard"]

保持 slug 简短。将文档放在 /docs 下

尽量使用简短的 slug。 不要为了匹配侧边栏中的每个分组而嵌套页面。

将信息文档放在 docs/ 父目录下，这样以后就可以在根目录添加落地页、工具和产品，而不会与文档 URL 冲突。

  URL                         file
  /                        ►  index.mdx          (home, product, landing)
  /pricing                 ►  pricing.mdx        (not a docs page)
  /docs/quickstart         ►  docs/quickstart.mdx
  /docs/sdk                ►  docs/sdk.mdx
  /docs/cli/query          ►  docs/cli/query.mdx   (max extra folder)

规则：

• 主页保留在根目录。 index.mdx 对应 /。
• 文档页面使用 /docs/...。 docs/quickstart.mdx 对应 /docs/quickstart。不要将指南放在 /quickstart 或 /guides/quickstart 下。
• 最多嵌套为 docs/<folder>/<page>。 docs 下最多只能有一个子目录（docs/cli/query.mdx）。绝不要使用 docs/cli/analytics/pages.mdx。
• 页面名绝不能是 README.md 或 README.mdx。 这两种文件名分别会对应 /README 或 /docs/README。请使用实际的 slug（docs/sdk.mdx），并导入共享 Markdown。
• 仅将 index 用于主页或分区主页。 不要将 README 用作主页文件名。
• 移动页面会更改其 URL。 从旧 slug 添加重定向，并更新 navigation.pages 和相对链接。构建过程中的失效链接检查会找出遗漏的链接。

navigation.global.anchors 中的锚点是持久的侧边栏链接，会显示在所有标签页中。可将其用于 GitHub、Changelog、Discord 或其他外部链接。

导航中的渐进式披露。 按照读者从上到下的阅读顺序排列分组、页面和标签页。先放介绍性内容（入门指南、快速入门），再放核心概念和指南，最后放进阶主题和参考资料。读者不应为了理解当前章节而需要跳到后面的内容。

标签页顺序。 在 navigation.tabs 中，先列出文档和指南，再列出 API 参考，最后列出更新日志。指向外部 URL（href）的标签页放在最后。这样可以引导读者从概念逐步了解参考资料。

图标

使用带前缀的图标名称，以明确其来源库：

"icon": "lucide:rocket"
"icon": "fontawesome:brands:github"

不带前缀的名称会根据已配置的库解析。完整参考请参阅 https://holocron.so/docs/customize/icons.md。

如果某个分组使用了图标，请勿在该分组的第一个页面上使用相同图标，否则它们在导航树中看起来会重复。

本地导入

MDX 页面可以导入 .md、.mdx、.tsx 或 .ts 文件。优先使用相对导入（./ 或 ../），而不是绝对导入 /。

使用包装页面复用共享 Markdown。 将 README.md、MCP.md 或 SDK Markdown 文件放在 pagesDir 之外，以便用于 GitHub。请勿将这些文件以 README.md 或 README.mdx 的形式放在 pagesDir 中。Holocron slug 就是文件路径，因此 sdk/README.mdx 会对应 /sdk/README。

pagesDir 中的包装页面负责公共 slug：

repo/
  README.md
  MCP.md
  website/src/pages/
    index.mdx
    docs/sdk.mdx          → /docs/sdk
    docs/mcp-setup.mdx    → /docs/mcp-setup

---
$schema: https://holocron.so/frontmatter.json
title: "MCP Setup"
sidebarTitle: MCP
---

import SharedDocs from '../../../../MCP.md'

<SharedDocs />

文件：docs/mcp-setup.mdx。导航 slug："docs/mcp-setup"。URL：/docs/mcp-setup。

如果旧的 /README 或 /sdk/README URL 已存在，请添加重定向：

"redirects": [
  { "source": "/sdk/README", "destination": "/docs/sdk", "permanent": true }
]

详情请参阅 https://holocron.so/docs/create/local-imports.md。

页面间链接

重要

内部链接必须始终使用相对路径（./ 或 ../）。绝不能使用以 / 开头的 绝对链接。

从一个页面到另一个页面的每个内部链接都必须：

1. 以 ./ 或 ../ 开头——相对于当前文件的路径。链接绝不能以 / 开头。
2. 指向磁盘上真实存在的目标文件——实际的 .md/.mdx 文件，而不是

路由或 slug。

3. 保留 .md/.mdx 扩展名。

✅ [SDK reference](./sdk.mdx)
✅ [Browser Analytics](./browser-analytics.mdx)
✅ [Quickstart](./quickstart.mdx)

❌ [SDK reference](/sdk/README)
❌ [Browser Analytics](/docs/browser-analytics)
❌ [Quickstart](/quickstart)

原因：绝对 /slug 链接会将路由写死，而路由取决于 pagesDir。同一个文件在不同项目中会生成不同的 slug （pagesDir: './src' 与 pagesDir: './src/pages'），因此绝对链接不可靠，并且在 pagesDir 或文件夹布局更改时会失效。指向真实文件的相对路径不依赖 pagesDir：Holocron 会将其解析为正确的路由并移除扩展名，而且该链接也会在 GitHub 上打开真实文件。

编写链接时，绝不要考虑 slug 或 pagesDir。 像在 GitHub 上那样，写出指向磁盘上实际文件的相对路径即可。剩下的交给 Holocron 处理。只有外部完整 URL（https://...）和 docs.json 中声明的 knownPaths 条目可以以 / 开头。

导入同时在 GitHub 上呈现的 README

一种常见做法是将仓库的 README.md 导入为文档索引页，这样同一个文件就能同时在 GitHub 和 Holocron 网站上呈现。README 会链接到其他文档（定价、指南、参考），这些链接必须在两处都有效。

规则很简单：始终使用正确的相对路径链接到真实目标文件，并以 .md 或 .mdx 结尾。 不要考虑 slug、pagesDir 或 / 最终指向哪里。像在 GitHub 上那样，写出从 README 到磁盘上实际文件的相对路径。

剩下的交给 Holocron 处理。内联导入的文件时，它会重新计算每个相对链接，使其相对于导入页面正确无误，然后移除 .md/.mdx 扩展名。因此，README 中指向真实文件的链接会自动跳转到该文件对应的页面，无需针对不同环境进行猜测。

规则

1. 链接到真实文件。 目标必须是在磁盘上、位于所写相对路径的实际 .md/.mdx 文件。这是 GitHub 链接有效的原因，也是 Holocron 重写链接的依据。如果文件不存在，GitHub 会返回 404，Holocron 的断链检查也会发出警告。

2. 始终使用相对路径（./ 或 ../），绝不要使用绝对路径。README 在 GitHub 和 Holocron 上呈现时的基准目录不同，因此绝对路径 /docs/x 或猜测的路径会导致其中一处失效。指向真实文件的相对路径在两处都有效，因为 Holocron 会重新计算路径。

3. 保留 .md/.mdx 扩展名。 GitHub 需要它来打开文件；Holocron 会自动移除扩展名，使链接指向呈现后的页面。

4. 目标文件必须是 pagesDir 内的页面。 Holocron 只会将指向 pagesDir 下文件的链接映射为页面。导入共享 Markdown 文件不会为该文件创建路由。从导入的 Markdown 中，应链接到 pagesDir 内的包装 .mdx 文件，而不是 README.md / MCP.md。

   [README.md](./README.md) 会变成 /README。请改用 [quick start](./website/src/pages/docs/quick-start.mdx)。

   README.md   [pricing](./docs/pricing.md)   ◄── correct relative path to a real file
        │
        ├──────────────────────► GitHub opens ./docs/pricing.md
        │
        ▼  imported into the index page
   Holocron recomputes the relative path ──► strips .md ──► lands on the page that renders pricing
        │
        ▼
   /docs/pricing   ◄── resolves as long as a page renders that file and it is in docs.json

如果重写后的 slug 没有对应页面，构建过程会输出断链警告，并指出 README 中的行号。请在 <pagesDir>/<slug>.mdx 创建页面（或创建一个导入共享 .md 的包装文件），并将其 slug 添加到 docs.json 导航中，以修复此问题。

README 文件中的 MDX JSX

不要在 README.md 中使用 MDX JSX 组件（例如 <Aside>、<Note>、<CardGroup>、 <Card> 等）。GitHub 不会呈现未知 HTML 标签中的 Markdown；其中的内容会以未格式化的原始文本显示。

README 中只能使用标准 Markdown。MDX 专用组件应放在导入 README 的 .mdx 文件中，而不是 README 本身。

页面 frontmatter

每个 MDX 页面都可以包含 YAML frontmatter。完整字段参考请参见 https://holocron.so/docs/create/pages.md。

---
$schema: https://holocron.so/frontmatter.json
title: Quickstart
description: Build and deploy your first Holocron docs site.
icon: lucide:rocket
tag: NEW
prompt: |
  Write the Quickstart from @/cli/src/create.ts.
---

记录生成提示词

创建的每个文档页面都必须包含一个 prompt 字段，记录生成该页面所用的指令和来源。编辑没有此字段的旧页面时，如果能识别实际来源，请添加该字段。编写最初的生成方案，而不是维护说明。

使用 @/path 引用仓库根目录下的源文件和文件夹。 只有当源文件与 MDX 页面位于同一目录或相邻目录时，才使用 @./path 或 @../path。 远程来源前缀使用 @https://。裸 URL 不算引用。 不要虚构来源；来源位置或页面范围发生变化时，请更新提示词。

---
$schema: https://holocron.so/frontmatter.json
title: Authentication
prompt: |
  Write the authentication guide from @/src/auth/ and
  @/src/middleware/session.ts.
  Use @https://github.com/example/project/releases for recent behavior.

  Explain sessions, API keys, and GitHub Actions OIDC.
  Include a complete TypeScript example for every method.
---

Holocron Maintain 会提取这些引用，并在来源变更时重新运行生成提示词。文件夹引用会匹配该文件夹内任意受跟踪文件的变更。

迁移现有文档站点

将文档站点迁移到 Holocron 时，编写每个 prompt 时都应假设页面是从头开始撰写的。简短概述页面记录的内容即可。

不要提及迁移、重新创建或旧文档的 URL。不要添加 @https://old-site/... 引用。除非用户另有说明，否则迁移完成后源站点将下线。

prompt: |
  Document connecting the first integration, role access, and chat validation.

Title 最多应为 50-60 个字符。它会以大号字体显示在 OG 图像、浏览器标签页和搜索结果中。请保持简洁且描述准确。

Sidebar title — 如果 title 超过 30 个字符，请在 frontmatter 中添加较短的 sidebarTitle 字段（少于 30 个字符）。左侧导航栏宽度仅为 230px；标题过长会换成多行，破坏视觉节奏。sidebarTitle 仅在侧边栏导航中替代标题；完整标题仍会显示在页面标题、浏览器标签页和 OG 图像中。

---
$schema: https://holocron.so/frontmatter.json
title: Configuring Authentication Providers
sidebarTitle: Auth Providers
---

Description 应为 120-150 个字符。它会显示在 OG 图像中标题下方，并出现在搜索引擎摘要中。请用一个句子概括页面内容。描述过长时会被省略号截断。

页面标题和 SEO（必须遵守）

Google 标题链接和摘要来自页面标题、H1 和描述。 请参阅标题链接 和摘要。

Holocron 已会附加站点名称。buildPageTitle 会渲染 {page title} — {site name}，除非 title 已以站点名称开头。 **不要在 title 或 H1 中填写站点名称。**否则品牌会重复 （Kimaki: … — Kimaki）。只写有助于排名的关键词。让 Holocron 添加 — {site name}。

两个 frontmatter 字段：

• title — 浏览器标签页、Google 标题链接、OG 图片和注入的 H1。请针对 SEO 撰写，填写此页面应获得排名的关键词。
• sidebarTitle — 仅用于侧边栏。简短标签，不超过 30 个字符。

**始终设置这两个字段。**如果不设置 sidebarTitle，较长的 SEO 标题会在 230px 的侧边栏中换行。

**始终为 frontmatter 字符串加引号。**YAML 会将 : 视为映射符号。title: Kimaki: AI agents 会被解析为嵌套 YAML。之后 Holocron 会丢弃所有 frontmatter，浏览器标题就会变成正文的第一个标题。如果未加引号的值中包含 :，或解析出的键包含空格和 :，Holocron 会发出警告。

---
$schema: https://holocron.so/frontmatter.json
title: "Open-source browser automation"
sidebarTitle: Home
description: "Automate any browser with a TypeScript API. Control Chrome from a CLI or agent."
---

浏览器标签页：Open-source browser automation — Playwriter 注入的 H1：Open-source browser automation 侧边栏：Home

在大多数页面上，Holocron 会将 title 注入为唯一的 H1，因此 title 和 H1 相同。保持这种设置。不要在正文中再添加一个 # 或 <h1>。

标题规则：

• **将有助于排名的关键词放入 title。**首页标题最为重要。文档页面应使用主题关键词（Subscriptions、Worktrees），而不是 Introduction 或 Overview。
• **title 不得以站点名称开头。**Holocron 已会附加 — {site name}。
• title 不得与站点名称相同。Playwriter 会变成 Playwriter — Playwriter。
• **每个 title 都必须唯一、准确且简洁。**Google 会截断过长的标题。避免堆砌关键词，以及只更改一个词的套话。
• index.mdx 必须使用 sidebarTitle: Home（或 Overview）。请参阅下文“首页 SEO”。

H1 规则：

• **每页只使用一个 H1。**其中必须包含与 title 相同的排名关键词。优先使用与 title 完全相同的文本。Holocron 注入标题时会自动实现这一点。
• Google 会将第一个醒目的 H1 用作标题链接的来源。同等醒目的额外 H1 可能会抢占标签页标题（Quick Start — Site）。标题数量不会影响排名，清晰的主标题才会。

描述规则：

description 会成为 <meta name="description">。如果描述比页面正文更能准确说明页面内容，Google 可能会将其用作摘要。

• **每页都要唯一。**在每个页面上使用相同的全站文案对搜索结果毫无帮助。
• **用一两句话概括此页面。**不要写成关键词列表。
• **自然地包含有助于排名的关键词。**不要堆砌关键词。标题后缀中已有站点名称，无须重复。首页摘要可提及一次产品名称。
• **写得具体。**长度没有硬性上限。Google 会根据设备宽度截断文本。建议使用简短介绍，约 120 至 160 个字符。
• 为 YAML 字符串加引号。

description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."

首页 SEO

首页标题是最强的品牌搜索信号。将用户搜索的关键词放入 title 和 H1 中。让 Holocron 追加站点名称。

---
$schema: https://holocron.so/frontmatter.json
title: "AI coding agents from Discord"
sidebarTitle: Home
description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
---

浏览器标签页：AI coding agents from Discord — Kimaki H1：AI coding agents from Discord

只使用一个 H1，且关键词与 title 相同。 除非页面包含 <Above> 或 hideTitle: true，否则 Holocron 会注入该 H1。自定义 Hero 如果也在注入的标题旁渲染 <h1>，就会产生两个 H1。

如果页面包含 <Above>，则该 Hero 负责显示 H1。 Holocron 会跳过注入标题。将 Hero 的 H1 设置为与 title 相同的文本。不要在 Hero 的 H1 中加入站点名称。不要在下方的 MDX 正文中使用 # 或 <h1>。正文的第一个章节必须使用 ##。多余的 H1 会降级为 H2。

---
title: "AI coding agents from Discord"
sidebarTitle: Home
description: "Run AI coding agents from Discord. Each channel is a project, each thread is a session."
---

<Above>
  <HeroSection />
</Above>

<h1>
  <span>AI coding agents</span>
  <span>from Discord.</span>
</h1>

如果没有自定义 Hero，不要设置 hideTitle。让 Holocron 将 title 注入为唯一的 H1。

不要让 / 成为 GitHub 的克隆。 在 Hero 下导入 README.md 没问题。首页仍需要自己的标题、H1 和描述。如果 / 与 GitHub 上的内容相同，Google 会优先选择 GitHub 页面以及一个独特的内层文档页面。

指向 / 的 Logo 链接作用有限。先修正标题、H1 和描述。

部署后，获取线上 HTML 并检查：

curl -sL -A 'Mozilla/5.0 (compatible; Googlebot/2.1)' 'https://example.com/' -o /tmp/home.html

确认恰好有一个 <h1>，其文本与 title 相同，并且 <title> 为 {title} — {site name}，站点名称只出现在末尾。在 Google 重新抓取之前，排名不会变化。

提升 Hero 背景上的文字可读性

文字叠加在 VideoBackgroundShader Hero 上时很难看清：动态字符会干扰文字。务必添加对比度图层。

**标题和 CTA：**添加径向遮罩层，让背景在中心位置淡出，并置于内容下方（z-[1]，低于 z-[2] 的文字）：

<div
  aria-hidden
  className='absolute inset-0 z-[1] pointer-events-none'
  style={{
    background:
      'radial-gradient(ellipse 45% 40% at 50% 42%, color-mix(in srgb, var(--background) 85%, transparent) 0%, color-mix(in srgb, var(--background) 60%, transparent) 50%, transparent 100%)',
  }}
/>

**副标题和小字：**为其添加模糊的半透明胶囊背景。没有这层背景时，低对比度的小字在动态字符上很难看清：

<p className='rounded-xl bg-background/50 px-3 py-1.5 text-sm text-muted-foreground backdrop-blur-md'>
  Paste the prompt into your agent
</p>

同时让 dotColor 接近页面背景色，以保持标题的对比度。

页面模式 — 隐藏侧边栏

在 frontmatter 中设置 mode 以隐藏侧边栏。适用于落地页、工具页，或不应显示左侧导航或 AI 聊天的页面。详情请参阅 https://holocron.so/docs/customize/layout.md。

• center — 隐藏左侧导航，并将内容居中。右侧栏仍然可用。
• custom — 隐藏两侧边栏和编辑网格。仅保留导航栏、标签栏和页脚。完整示例请参阅 example/src/landing.mdx。

这两种模式下，内容都可能显得过宽。使用 maxWidth 限制宽度：

---
$schema: https://holocron.so/frontmatter.json
mode: "custom"
maxWidth: 700
---

自定义入口（在 Spiceflow 应用中挂载文档）

当网站在现有的 Spiceflow 应用中挂载 Holocron 时（Vite 插件中的 entry 选项），务必先获取自定义入口文档。本页介绍中间件顺序、共享主题 Cookie、Tailwind @reference 规则，以及如何将文档（包括 OpenAPI 和 Changelog 标签页）保留在 /docs/* 命名空间下，避免与 /api 等应用路由冲突：

curl -fsSL https://holocron.so/docs/custom-entry.md

重定向

重组文档时，请在 docs.json 中添加重定向。完整参考请参阅 https://holocron.so/docs/create/redirects.md。

失效链接检测

如果内部链接指向不存在的页面，Holocron 会使生产构建失败。开发模式仍会发出警告。MDX、页脚、导航栏和锚点中的链接都会检查。指向重定向源和静态文件（.json、.pdf 等）的链接不会被标记。警告会包含来源、行号和失效的 href，方便你快速找到并修复问题。

除非某个路由在运行时确实存在，否则不要将其路径放入 knownPaths。knownPaths 只会关闭检查，不会创建页面。

使用 knownPaths 抑制误报

当文档与其他路由（API 端点、仪表板、博客）一起挂载时，指向这些非 MDX 路径的内部链接会触发错误的损坏链接警告。使用 docs.json 中的 knownPaths 字段告知 Holocron 这些路径有效：

{
  "knownPaths": ["/api/*", "/dashboard", "/blog/*"]
}

支持的模式：

• 精确路径 — "/dashboard" 仅匹配 /dashboard。
• 通配符前缀 — "/api/*" 匹配 /api/users、/api/v2/health，以及其他所有以 /api/ 开头的路径。

通配符仅支持以 /* 结尾的后缀。不支持 /api/*/users 之类的 Glob 模式。

包装器内的垂直间距

将 MDX 内容包裹在 <div> 或自定义组件中时，添加 flex flex-col gap-(--prose-gap)，以确保子元素获得正确的垂直间距。否则，元素会挤在一起。如果包装器包含不应超出其边界的图像或代码块，也添加 no-bleed。

<div className='no-bleed flex flex-col gap-(--prose-gap)'>

First paragraph.

Second paragraph with correct spacing above.

</div>

MDX 容器组件

对于 Callout、Note、Warning、Info、Tip、Check、Danger、Aside、Accordion、Steps、Card、Expandable、Panel、Frame 和 Prompt 等容器组件，始终使用多行形式。

<Note>
Use `Note` for neutral supporting information.
</Note>

单行形式可能会产生没有段落包装的裸短语子元素，从而改变样式。

原生标题（h1-h6）会自动修复；无论使用哪种形式，Holocron 都会移除段落包装。对于其他类似叶节点的元素（<span>、<div> 或大写的自定义组件），使用单行形式以避免包装。

<MyBanner className='text-xl'>Short announcement text</MyBanner>

Aside 内容

Aside 仅用于定位，不带视觉边框。始终将可见内容包裹在 Note、Tip、Info、Warning、Callout 或其他带边框的组件中。

<Aside>
<Note>
This appears in the sidebar with a proper callout frame.
</Note>
</Aside>

例外：Aside full 可以直接包含 TableOfContentsPanel。

仅在内容足够充实的章节中使用 <Aside>。 非全宽的 Aside 会与其所属章节共享垂直空间（即两个标题之间的内容）。如果 Aside 比章节正文更高，主内容下方就会出现额外的空白，以容纳 Aside 的高度。保持 Aside 提示简短，并且只将其放在至少有几个正文段落的章节中。

移动或重命名页面

移动或重命名页面时，始终添加重定向，将旧路径指向新路径，以确保旧 URL 和书签仍然有效。更新其他页面中的内部链接，以及 docs.json 导航中的 slug，使其保持一致。

将重定向添加到 docs.json 中的 redirects 数组：

{
  "redirects": [
    { "source": "/old-page", "destination": "/new-page" },
    { "source": "/guides/setup", "destination": "/docs/setup", "permanent": true },
    // wildcard: redirect a whole moved folder (:splat = matched suffix)
    { "source": "/v1/*", "destination": "/v2/:splat" }
  ]
}

source 和 destination 是绝对路径（以 / 开头，不含扩展名）。添加 "permanent": true 可设置为 301（默认值为 302）。完整参考请参阅 https://holocron.so/docs/create/redirects.md。

新页面和导航

创建新的 .mdx 或 .md 页面后，将其 slug 添加到 docs.jsonc 导航中。不在导航树中的页面不会显示在侧边栏中，并会返回 404。

先阅读现有导航结构，然后将页面放在最合适的标签页、分组和阅读顺序中。

法律与支持页面：隐藏分组加页脚

隐私政策、服务条款、支持页面及类似页面对读者没有吸引力。不要在侧边栏中显示它们。将它们放入 "hidden": true 的分组中（仍会提供访问并建立索引），并从 footer.links 链接到这些页面：

{
  "navigation": {
    "groups": [
      // ...real docs groups
      {
        "group": "Legal",
        "hidden": true,
        "pages": ["docs/privacy", "docs/terms", "docs/support"]
      }
    ]
  },
  "footer": {
    "links": [
      {
        "header": "Legal",
        "items": [
          { "label": "Privacy", "href": "/docs/privacy" },
          { "label": "Terms", "href": "/docs/terms" },
          { "label": "Support", "href": "/docs/support" }
        ]
      }
    ]
  }
}

使用分组的 hidden 标志，不要在页面 frontmatter 中设置 hidden: true：frontmatter 中的 hidden 还会添加 noindex。为标准短路径（/privacy、/terms、/support）添加 "redirects"，并设置 "permanent": true，因为应用商店和 OAuth 同意页面通常会要求这些路径。

新内容应放在哪里

实际文档位于 website/src/pages/docs/，而不是 example/src/。example/ 文件夹是演示用的测试夹具，不是已发布的文档站点。

添加或编辑文档内容前，务必先阅读 website/docs.json， 了解完整的导航树和现有页面。然后判断：

1. 是否已有页面涵盖此主题？在该页面中添加一个章节。
2. 该主题是否足够独立，适合单独建页？创建一个新的 .mdx 文件，并 将其添加到 website/docs.json 中最合适的分组。

切勿仅仅因为某个页面是你最后打开的文件，就在其中追加不相关的章节。 应将主题放到正确的页面，或创建新页面。

反馈循环

编辑 MDX 页面、docs.json 导航或 frontmatter 后，务必构建站点， 尽早发现问题。构建过程可以检测损坏的内部链接、MDX 解析错误、导航中引用但缺失的页面，以及渲染问题；这些问题可能要等到访问相应页面时才会在开发服务器中显现。

pnpm build

完成修改前，先修复所有警告或错误。常见问题包括：

• 损坏的链接——指向导航中不存在的 slug 的内部 [link](/some-page)。
• MDX 解析错误——格式错误的 JSX、未闭合的标签，或无效的 frontmatter YAML。
• 缺失的页面——docs.json 导航中列出了某个 slug，但没有对应的 .mdx 文件。
• 渲染错误——组件使用不当（例如 props 错误、缺少子元素）。

如果构建针对运行时存在、但不是 MDX 页面的路径（API 路由、与文档并行挂载的外部应用、仪表板页面）发出链接警告，请使用 docs.json 中的 knownPaths 字段抑制这些警告。请参阅上文的损坏链接检测 章节。

CLI 概览

运行 --help 查看所有可用命令。切勿截断输出。

npx -y "@holocron.so/cli" --help

主要命令：login、logout、whoami、deploy、projects list、 projects create、keys list、keys create、keys delete、create。

登录前，务必先检查用户是否已通过身份验证：

npx -y "@holocron.so/cli" whoami

如果 whoami 成功并显示用户、组织和项目，则跳过登录。只有在 whoami 失败时，才运行 npx -y "@holocron.so/cli" login。

部署

用户要求“部署站点”时，可能指的是使用自己的脚本和平台部署（Cloudflare Workers、Node 服务器、CI 流水线），而不是 holocron deploy。先检查 package.json 脚本：如果其中有 deploy、 deployment 或类似脚本（例如 wrangler deploy），请使用该脚本，而不是 Holocron CLI。只有当项目没有自己的部署脚本，或用户明确要求使用 holocron.so 托管时，才使用 holocron deploy。

holocron deploy 会构建文档站点，并将其上传到 holocron.so 托管服务。 这是无需自行管理服务器即可快速发布的方式。

npx -y "@holocron.so/cli" deploy

该命令会运行构建、仅上传变更文件、完成部署，并打印线上 URL。如果账户有多个 项目且你使用的是会话身份验证，请使用 --project prj_xxx。预览部署时，请使用 --branch <name> 覆盖 分支检测。

身份验证优先级： HOLOCRON_KEY 环境变量 > holocron login 获取的会话令牌 > GitHub Actions OIDC 令牌（在 GitHub Actions 中配置 id-token: write 后自动使用）。

完整参考文档（包括部署 URL、GitHub Actions OIDC 设置以及组织/项目解析）请参阅 https://holocron.so/docs/deploy/holocron.md。

务必先部署预览环境，再部署生产环境。如果预览部署失败，请停止操作。

图标一致性

向 docs.json 或 MDX 前置元数据中的任何元素添加图标时，请在同一级别的所有同级元素中保持一致。图标使用不一致会显得不够完善，也会破坏视觉节奏。

规则：

• 选项卡：如果一个选项卡有图标，每个选项卡都必须有图标。
• 分组：如果一个侧边栏分组有图标，同一选项卡中的所有同级分组都应有图标。
• 锚点：如果 navigation.global.anchors 中的一个锚点有图标，所有锚点都必须有图标。
• 页面：如果某个分组中的一个页面在前置元数据中设置了 icon，该分组中的所有页面都应设置图标。例外：分组只有 1-2 个页面，且图标不具备导航价值时。
• 卡片 / CardGroup：如果 <CardGroup> 中的一个 <Card> 设置了 icon 属性，该组中的每张卡片都必须设置。
• Accordion / AccordionGroup：规则相同。所有项目要么都有图标，要么都没有。

检查或创建导航和 MDX 内容时，请查看同级元素，并在完成前为缺少图标的元素补上图标。使用同一图标库（通常为 Lucide）中的图标，并为每个项目选择语义上不同的图标。

MDX 页面写作风格

加粗关键词，便于快速浏览

每个章节和每个段落都必须至少包含一个加粗的关键词或短语。读者浏览文档页面时不会逐字阅读。加粗文本充当锚点，让读者一眼就能找到相关段落。

选择能概括核心思想的词语或短语。不要将整句话或泛泛的填充词加粗。应加粗读者会重点查找的具体术语、API 名称或概念。

经常使用 Aside 放置补充内容

经常使用 <Aside>，将补充内容放在右侧边栏中。Aside 能打破单栏文本流的单调感，并在相关位置为读者提供背景说明。完全没有 Aside 的页面显得单调，也未能充分利用版面。

适合放入 Aside 的内容：

• 与当前章节相关、但不属于正文叙述的提示和注意事项
• 版本说明或兼容性警告
• 相关页面或外部参考资料的链接
• 展示替代方案或边缘情况的简短代码片段
• 正文中提到的术语的定义或说明

始终使用带边框的组件（Note、Tip、Info、Warning、Callout）包裹 Aside 内容。

## Authentication

The deploy command authenticates via **GitHub Actions OIDC** when running in CI.

<Aside>
<Info>
If OIDC is not available, fall back to a **`HOLOCRON_KEY`** environment variable
or a session token from `holocron login`.
</Info>
</Aside>

目标是每个主要章节（每个 ## 标题）大约添加一个 Aside。并非每个章节都需要 Aside；但如果一个页面中有三个以上的 ## 章节，却一个 Aside 都没有，请寻找合适的添加位置。

较短的章节中不要使用 Aside。 非全宽 Aside 会与所在章节（两个标题之间的文本）共享垂直空间。如果 Aside 提示框比章节正文更高，主要内容下方就会出现空白。只有在正文足够长、能与 Aside 高度相当或超过它时，才添加 Aside。提示框应简洁（1-2 句）。

使用图表说明架构和流程

在 MDX 页面中经常使用 ASCII 图表。代码围栏始终使用 diagram 语言提示。Holocron 会对 diagram 围栏进行特殊渲染；Unicode 制表符和箭头会以不同于标签的颜色显示。

布局规则：

• 图表应尽量覆盖内容栏的全宽，宽度大约为 94 个字符。
• 每行不得超过 94 个字符。
• 尽量采用多样、自然的布局。混合使用纯文本标签、主要组件的方框和方向箭头。
• 所有连接都必须使用方向箭头。不得使用没有箭头的普通线条。
• 运行 npx -y "@holocron.so/cli" diagrams fix <file> 检查对齐情况（参见下方专门章节）。

```diagram
                ┌───────────────┐
docs.jsonc ───►│  Vite Plugin  │──────► Build Output
               └───────┬───────┘
                       │
               ┌───────▼───────┐
               │   sync.ts     │  MDX files ──► parsed sections
               │  (walk nav)   │  git SHA diff ──► cache hit/miss
               └───────┬───────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
    navigation    page cache    virtual modules
    tree.json     holocron-mdx   holocron-pages
                  holocron-config holocron-config
```

编辑图表或表格后，始终运行 diagrams fix

LLM 无法可靠地统计字符或填充表格列。每次在 MDX 页面中创建或编辑图表或 GFM 表格时，提交前都必须运行修复工具。这不是可选步骤。

npx -y "@holocron.so/cli" diagrams fix path/to/file.mdx

此命令：

• 就地修复框线图的对齐（填充、边框宽度、连接处）
• 格式化 GFM 表格（列填充、对齐竖线、上下空行）
• 报告更改的行数
• 如果任何图表行超过最大宽度（默认 94 列），或表格仍需格式化（--check），则以代码 1 退出

如果输出显示“No changes”，说明文件原本就是正确的。如果报告了宽度违规，请手动缩短有问题的图表行，然后重新运行。

不要跳过此步骤。 即使图表或表格在编辑器中看起来没问题，也要运行该命令。差一位的填充和不均匀的表格列对 LLM 来说难以察觉，但在人类使用等宽字体查看时却很明显。

OpenAPI 摘要

OpenAPI 操作的 summary 字段会成为侧边栏标题。侧边栏宽度只有 230px，因此摘要必须简短：2～3 个词，最好少于 20 个字符。采用与页面 sidebarTitle 字段相同的精简风格。

• 动词 + 名词模式：List users、Create order、Get me、Upload files。
• 删除限定语、括号内容和实现细节。Upload deployment files (zip batch) 应改为 Upload files。
• 摘要中不要重复标签/分组名称。如果标签是 Deploy，摘要就不应以“Deploy”开头。
• 如果摘要作为 230px 宽的侧边栏标签读起来很自然，就足够简短。

Bleed — 将内容延伸到正文栏之外

始终将 YouTube 嵌入内容、视频和大图片包裹在 <div className='bleed'> 中， 使其延伸到页面两侧的边距，而不是局限在较窄的正文宽度内。 <Frame> 也支持 className='bleed'。Callout、Card 和 Accordion 等容器会自动应用 no-bleed，使后代内容保持在其框架内。

完整参考请参阅 https://holocron.so/docs/customize/bleed.md。

自定义 CSS — 优先使用 CSS 变量，而非类选择器

自定义 Holocron 网站外观时，始终在 :root 中使用 CSS 变量覆盖，而不要定位内部类名、DOM 结构或 aria 标签。Holocron 提供一组有文档说明的 CSS 变量，用于颜色、排版、间距、代码块、引用块和侧边栏导航。这些变量在 Holocron 更新中保持稳定；内部标记则不会。

/* style.css */
:root {
  --weight-heading: 700;
  --code-block-background: var(--muted);
  --code-block-border: 1px solid var(--border-subtle);
  --sidebar-link-radius: var(--radius-sm);
  --blockquote-border-color: var(--border-subtle);
}

获取所有可用令牌的列表：

curl -fsSL https://holocron.so/docs/customize/theme.md

如果用户想自定义的内容没有对应的 CSS 变量，不要用脆弱的选择器来变通。请改为在 Holocron 仓库中提交 issue（https://github.com/remorses/holocron/issues），请求为该用例新增 CSS 变量。Holocron 会根据用户需求积极添加新变量。.slot-sidebar-left nav > div:first-child > a 或 figure[class~='group/code'] button[aria-label='Copy code'] 这类内部选择器会在任何重构中失效，因此绝不应使用。

Agent 规则

• 始终将 MDX 页面放在 Holocron 的 pagesDir 中。 创建或编辑任何文档页面之前，先读取项目的 vite.config.ts（或 vite.config.mts），找到传递给 Holocron 插件的 pagesDir 选项。如果未设置 pagesDir，则默认为项目根目录。所有 .mdx 和 .md 页面文件都必须放在该目录中；目录之外的文件不会显示在导航中，也不会参与构建。
• 优先使用最新获取的文档，而非依赖之前会话中的记忆。
• 将类似规则的项目行为保留在此技能中，以便 Agent 在获取完整文档之前就能看到。
• MDX 页面中的所有 ASCII 图示都必须在代码围栏中使用 diagram 语言标记（```diagram）。这样可以让网站以适当样式渲染图示，而不是显示为纯等宽文本。
• 创建或编辑任何图示或 GFM 表格后，运行 npx -y "@holocron.so/cli" diagrams fix <file>，自动修正图示对齐和表格列填充。大模型无法可靠地统计字符或填充列。
• 切勿将 curl 或 --help 的输出通过 head、tail 或任何截断命令进行管道处理。始终阅读完整输出。