{page.title}

# @clusterize/bundoc 中文文档

规范地址：https://npmcn.com/package/%40clusterize/bundoc/

版本：0\.4\.0
npm 元数据更新时间：2026-10-20T09:24:17.722Z
中文译文更新时间：2026-11-10T09:23:29.861Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40clusterize/bundoc
原文对照：https://npmcn.com/package/%40clusterize/bundoc/?lang=original
项目主页：https://bundoc.dev/
源码仓库：https://github.com/clusterize/bundoc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：162 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：16 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0，playwright \>=1\.40，typescript ^5
- 首次发布：2026-05-13T13:08:36.217Z
- 最新版本发布：2026-10-20T09:24:17.362Z
- 近 30 天下载量：1868（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

用Bun和MDX构建的现代自带组件文档框架.

## 安装

```sh
npm install @clusterize/bundoc
```

也可以使用：`pnpm add @clusterize/bundoc`、`yarn add @clusterize/bundoc`、`bun add @clusterize/bundoc`

## README

# bundoc 语录

用于 MDX 文件站点的 Bun-native CLI **把主题带回来** 型号。 Bundoc拥有无聊的部分——内容发现,MDX编译,, 路由,i18n,搜索——并被曝光为反应钩. 你拥有每一个 uI的像素.

> **要求数 [阿宝](https://bun.sh/) ≥ 1.3.** bundoc是仅Bun。 飞船 直接使用脚本源 `Bun.serve` 编号 : `Bun.build`它会 不在节点下运行.

```bash
bunx @clusterize/bundoc init my-docs
cd my-docs
bun install
bunx @clusterize/bundoc dev
```

打开 `http://localhost:3000`。 。 。 .

* * *

## 为什么Bundoc

大多数文件工具或将您锁定到一个主题( Docusaurus, Mintlify) , 或 让你用Next.js的电线 来制造马克道, (原始内容存档于2018-09-26). fumadocs. bundoc坐落在:

-   **内容是 `.mdx`** 前题 GFM 标题 代码块.
-   **主题为您的 React app** ——没有皮肤系统,没有有观点的布局. 你从这里进口了几根钩子 `bundoc/theme` 并创造任何物 想要吗.
-   **其他东西都在里面** ——文件系统路由,i18n与 倒计时 Orama 搜索索引 可选 Shiki 突出显示 .

输出是完全静态的 SPA(`bundoc build`没有服务器运行时间, 没有Lambda,没有边缘工人。 丢弃 `dist/` 在任何静态主机.

* * *

## 解剖工程

`bundoc init` 写给你:

```
my-docs/
├─ bundoc.config.ts        # locales, paths, mdx pipeline
├─ content/
│  ├─ index.mdx            # → /
│  ├─ index.de.mdx         # → /de
│  └─ guides/
│     ├─ _meta.json        # ordering + labels (optional)
│     └─ install.mdx       # → /guides/install
├─ public/                 # static assets copied verbatim to the site
│                          # root at build, served as-is in dev
└─ theme/
   ├─ index.tsx            # your <App/> — mounted inside bundoc providers
   └─ mdx-components.tsx   # optional: { h1, code, pre, ... }
```

### 公约

-   **默认位置无前缀**,其他前缀为: `/foo` 对 `/de/foo`。 。 。 .
-   **`index.mdx`** 是目录的索引路径.
-   **`_meta.json`** 在任何子目录中提供 `{ order, label }` 覆盖; 其他字母顺序 `frontmatter.title` qq 文件名 .
-   **开始的文件 `_` 或者说 `.`** 被忽略.
-   **i18n 文件名**数字 : `install.mdx` 是默认本地页面; `install.de.mdx` 是德文翻译。 翻译缺失倒数 自动返回默认区域.

* * *

## 写入主题

其主题是常规回放组件. Bundoc将它挂在它的里面 提供商,所以钩子"只是工作。"

```tsx
// theme/index.tsx
import {
  PageOutlet,
  Link,
  useNav,
  useCurrentPage,
  useLocale,
  useTOC,
} from "@clusterize/bundoc/theme";

export default function ThemeApp() {
  const nav = useNav();              // tree, flat, currentPath, prev, next
  const { locale, locales, setLocale } = useLocale();
  const page = useCurrentPage();     // { route, title, frontmatter, ... }
  const headings = useTOC();         // current page's h2/h3/h4

  return (
    <div className="layout">
      <aside>
        <LocaleSwitcher locales={locales} current={locale} onChange={setLocale} />
        <Sidebar tree={nav.tree} />
      </aside>
      <main>
        <h1>{page.title}</h1>
        <PageOutlet fallback={<p>Loading…</p>} />
      </main>
      <TOC items={headings} />
    </div>
  );
}
```

所有东西都是你的——造型,布局,动画,黑暗模式,搜索 调色板,命令栏。 这个 [文件站点](https://bundoc.dev/) 本身是一个 bundoc 主题; 下方来源 [`packages/docs`](https://github.com/clusterize/bundoc/tree/main/packages/docs) 是一个很好的全脂参考文献( 侧边栏、 粘贴 TOC、 QQK 搜索、 本地化) 交换机,双主题Shiki).

### MDX 组件覆盖

`theme/mdx-components.tsx` 导出应用于每个 MDX 页面的地图 :

```tsx
// theme/mdx-components.tsx
const components = {
  h1: (props) => <h1 className="text-3xl font-bold" {...props} />,
  a:  (props) => <a className="underline" {...props} />,
  pre: (props) => <pre className="rounded-md p-4" {...props} />,
  code: (props) => <code className="font-mono text-sm" {...props} />,
  // Custom components MDX authors can use directly inside .mdx files:
  // Callout,
};

export default components;
```

默认的 Bundoc 释放出未设置的 `<pre><code class="language-ts">…</code></pre>`。 。 。 . 在覆盖图中设置样式, 或启用 [志纪](https://npmcn.com/package/%40clusterize/bundoc/#readme-syntax-highlighting)。 。 。 .

### 公共钩子

| 钩子 | 它的回报 |
| --- | --- |
| `useNav()` | `{ tree, flat, currentPath, prev, next }` 当前区域 |
| `useCurrentPage()` | `{ route, locale, title, frontmatter, headings, fallback, notFound }` |
| `useTOC()` | `Heading[]` 从当前页 (h2/h3/h4) |
| `useLocale()` | `{ locale, locales, defaultLocale, setLocale }` |
| `useLink()` | `(to: string) => href` ——地方意识花卉建筑师 |
| `useFrontmatter<T>()` | 进取糖 `useCurrentPage().frontmatter` |
| `useSearchIndex()` | 查询构建时 Orama 索引的懒惰客户端 |
| `<Link to=… />` | 地方意识 `<a>` 包装 |
| `<PageOutlet />` | 当前 MDX 页面生成的槽 |

路由器和提供者为运行时拥有;主题代码只消耗 钩子. 这保持了未来公司社会责任和安保部门改革工作合同的稳定.

* * *

## 配置

`bundoc.config.ts`数字 :

```ts
import { defineConfig } from "@clusterize/bundoc/config";

export default defineConfig({
  locales: ["en", "de"],
  defaultLocale: "en",
  contentDir: "./content",          // default
  themeEntry: "./theme/index.tsx",  // default
  basePath: "/",                    // for hosting under a subpath
  mdx: {
    highlighting: { light: "github-light", dark: "github-dark" },
  },
  search: {
    // Honour `search: false` in frontmatter. Replace or extend
    // for route-prefix exclusion, draft filtering, etc.
    filter: (page) => page.frontmatter.search !== false,
  },
});
```

### 语法突出显示

默认关闭。 设定 `mdx.highlighting: true` (或通过主题名称)改为 启用有双重光/暗 CSS变量的建置时间Shiki。 切换 通过一个 `html.dark` 课程在您的根上——您的主题决定 何时适用.

### 搜索

总是在。 在建设时间 Bundoc走 每个MDX,提取 纯文本,并写一个 Orama BM25 索引 `dist/_bundoc/search/<locale>.json`。 。 。 . `useSearchIndex()` 懒惰的 客户端。 没有服务器,没有API密钥,没有第三方.

包容的规范是: `search.filter` 内 `bundoc.config.ts`编辑 默认的上游荣誉 `frontmatter.search !== false` - 通过你的 本身可以按路由前缀、地块、旗子草稿或任何组合排除. 上游签名导出为 `SearchablePage` 默认 作为 `defaultSearchFilter`,因此可以延长而不是替换.

* * *

## 图标

| 命令 | 它会做什么 |
| --- | --- |
| `bundoc dev` | 使用 HMR 的 Dev 服务器 `localhost:3000`。 。 。 . |
| `bundoc build` | 静态站点到 `dist/`。 。 。 . |
| `bundoc preview` | 服务 `dist/` 与SPA倒置. |
| `bundoc pdf` | 每个地方的 PDF 手册 `dist/_bundoc/pdf/` (需要剧作家). |
| `bundoc init <dir>` | 脚手架新项目. |

旗帜 : `--port`, (中文(简体) ), `--host`, (中文(简体) ), `--out`, (中文(简体) ), `--locale`运行 `bundoc --help`。 。 。 .

### `bunfig.toml` 插件

任何你放进去的东西 `[serve.static].plugins` 两者均适用 `bundoc dev` _财务报告和审定财务报表_ `bundoc build` ——用于Tailwind,PostCSS等.

* * *

## 状态

bundoc 为 **预加1.0**。上面列出的钩子是稳定的;内部的 没有。 全面参考和路线图 [bundoc.dev (英语)](https://bundoc.dev/)。 。 。 .

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40clusterize/bundoc/LICENSE)。 。 。 .

## 常见问题

### @clusterize/bundoc 是什么？

用Bun和MDX构建的现代自带组件文档框架\.

### 如何安装 @clusterize/bundoc？

在项目目录运行 npm install @clusterize/bundoc，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 bundoc，可以用 npx bundoc 直接运行。

### @clusterize/bundoc 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/clusterize\_\_bundoc 是否存在。

### @clusterize/bundoc 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @clusterize/bundoc 可以商用吗？

@clusterize/bundoc 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @clusterize/bundoc 的下载量有多少？

根据 npm 官方下载统计，@clusterize/bundoc 在 2026/10/10 – 2026/11/08 这 30 天内被下载 1,868 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @clusterize/bundoc 还在维护吗？

最新版本 0\.4\.0 发布于 2026/10/20（21 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。