From doc-smith
Builds Doc-Smith Markdown documentation into static HTML sites, generating nav.js navigation data, CSS assets, TOC, and relative asset paths for images.
npx claudepluginhub aigne-io/doc-smith-skills --plugin doc-smithThis skill uses the workspace's default tool permissions.
双模式构建:`--nav` 生成导航和静态资源,`--doc` 构建单篇文档。
Generates documentation for codebases—from file references and feature guides to full sites. Detects and adapts to frameworks like Fumadocs, Nextra, Docusaurus.
References MkDocs CLI commands, mkdocs.yml settings, Material theme customization, and plugins for building static documentation sites from Markdown files.
Share bugs, ideas, or general feedback.
双模式构建:--nav 生成导航和静态资源,--doc 构建单篇文档。
# 生成 nav.js + 复制资源 + 创建重定向
node skills/doc-smith-build/scripts/build.mjs \
--nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist
# 构建单篇文档
node skills/doc-smith-build/scripts/build.mjs \
--doc .aigne/doc-smith/docs/overview/zh.md --path /overview \
--workspace .aigne/doc-smith --output .aigne/doc-smith/dist
| Option | Alias | Description |
|---|---|---|
--nav | 生成 nav.js、复制 CSS、创建重定向页面 | |
--doc <file> | 构建单篇 MD 文件为 HTML | |
--path <path> | 文档路径(如 /overview),--doc 模式必需 | |
--workspace <path> | -w | Doc-Smith workspace(默认 .aigne/doc-smith) |
--output <path> | -o | 输出目录(默认 <workspace>/dist) |
从 document-structure.yaml + config.yaml 生成导航数据和静态资源。
输出:
assets/nav.js — 导航数据(window.__DS_NAV__ = {...}),侧边栏和语言切换由此驱动assets/docsmith.css — 内置基础样式assets/theme.css — 用户主题(不存在时创建空文件)index.html — 根重定向{lang}/index.html — 语言重定向调用时机: 初始化时、文档结构变更后。
构建单篇 MD 文件为完整 HTML 页面。
输入: MD 文件路径 + 文档 path
输出: dist/{lang}/docs/{path}.html
职责:
<!-- afs:image ... -->)/assets/ 路径转换为相对路径(见下方路径契约)不负责: 导航渲染(nav.js 客户端完成)、MD 清理(调用方负责)。
MD 文件中使用 /assets/ 绝对路径引用资源,build.mjs 自动转换为相对路径:
| MD 中写法 | HTML 输出(depth=1) | HTML 输出(depth=2) |
|---|---|---|
 | ../../assets/logo.png | ../../../assets/logo.png |
.. 的视为非法,不转换(防遍历攻击)../../assets/ 仍由已有逻辑处理(向后兼容)侧边栏和语言切换由 nav.js 在客户端渲染:
<script src> 加载(兼容 file:// 和 http:// 协议)| 错误类型 | 处理方式 |
|---|---|
| workspace 不存在 | 报告明确错误 |
| document-structure.yaml 缺失 | 报告明确错误 |
| MD 文件不存在 | 报告明确错误 |
--doc 缺少 --path | 报告明确错误 |
| 依赖未安装 | 在 scripts 目录执行 npm install |
如果执行脚本时出现模块找不到的错误,需要先安装依赖:
cd skills/doc-smith-build/scripts && npm install
.aigne/doc-smith/dist/
├── index.html # 重定向到主语言
├── zh/
│ ├── index.html # 中文首页
│ └── docs/
│ ├── overview.html
│ └── guide/
│ └── intro.html
├── en/
│ ├── index.html # 英文首页
│ └── docs/
│ └── ...
└── assets/
├── docsmith.css # 内置基础样式
├── theme.css # 用户主题
└── nav.js # 导航数据(侧边栏 + 语言切换)