bundoc 语录
用于 MDX 文件站点的 Bun-native CLI 把主题带回来 型号。 Bundoc拥有无聊的部分——内容发现,MDX编译,, 路由,i18n,搜索——并被曝光为反应钩. 你拥有每一个 uI的像素.
要求数 阿宝 ≥ 1.3. bundoc是仅Bun。 飞船 直接使用脚本源
Bun.serve编号 :Bun.build它会 不在节点下运行.
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.titleqq 文件名 .- 开始的文件
_或者说.被忽略. - i18n 文件名数字 :
install.mdx是默认本地页面;install.de.mdx是德文翻译。 翻译缺失倒数 自动返回默认区域.
写入主题
其主题是常规回放组件. Bundoc将它挂在它的里面 提供商,所以钩子"只是工作。"
// 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>
);
}
所有东西都是你的——造型,布局,动画,黑暗模式,搜索
调色板,命令栏。 这个 文件站点 本身是一个
bundoc 主题; 下方来源
packages/docs
是一个很好的全脂参考文献( 侧边栏、 粘贴 TOC、 QQK 搜索、 本地化)
交换机,双主题Shiki).
MDX 组件覆盖
theme/mdx-components.tsx 导出应用于每个 MDX 页面的地图 :
// 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>。 。 。 .
在覆盖图中设置样式, 或启用 志纪。 。 。 .
公共钩子
| 钩子 | 它的回报 |
|---|---|
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数字 :
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 (英语)。 。 。 .
许可证
麻省理工学院——见 自由主义。 。 。 .