Doc Smith Build

Doc-Smith HTML 构建

双模式构建：--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 | | 构建单篇 MD 文件为 HTML | | --path | | 文档路径（如 /overview），--doc 模式必需 | | --workspace | -w | Doc-Smith workspace（默认 .aigne/doc-smith） | | --output | -o | 输出目录（默认 /dist） |

模式说明

--nav 模式

从 document-structure.yaml + config.yaml 生成导航数据和静态资源。

输出：

• assets/nav.js — 导航数据（window.__DS_NAV__ = {...}），侧边栏和语言切换由此驱动
• assets/docsmith.css — 内置基础样式
• assets/theme.css — 用户主题（不存在时创建空文件）
• index.html — 根重定向
• {lang}/index.html — 语言重定向

调用时机： 初始化时、文档结构变更后。

--doc 模式

构建单篇 MD 文件为完整 HTML 页面。

输入： MD 文件路径 + 文档 path 输出： dist/{lang}/docs/{path}.html

职责：

• Markdown → HTML 转换（markdown-it）
• 套 HTML 骨架（data-ds 锚点）
• 生成 TOC（页面内联）
• 处理图片占位符（``）
• /assets/ 路径转换为相对路径（见下方路径契约）
• 拼接静态资源引用（CSS + nav.js）

不负责： 导航渲染（nav.js 客户端完成）、MD 清理（调用方负责）。

路径契约

MD 文件中使用 /assets/ 绝对路径引用资源，build.mjs 自动转换为相对路径：

| MD 中写法 | HTML 输出（depth=1） | HTML 输出（depth=2） | |-----------|---------------------|---------------------| | ` | ../../assets/logo.png | ../../../assets/logo.png` |

• 路径包含 .. 的视为非法，不转换（防遍历攻击）
• 旧格式 ../../assets/ 仍由已有逻辑处理（向后兼容）
• 外部 URL 不受影响

导航架构

侧边栏和语言切换由 nav.js 在客户端渲染：

• 使用 ` 加载（兼容 file:// 和 http://` 协议）
• 更新文档结构只需重新生成 nav.js，无需重建所有 HTML 页面
• TOC 仍在构建时内联生成（页面特有内容）

错误处理

| 错误类型 | 处理方式 | |----------|----------| | 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              # 导航数据（侧边栏 + 语言切换）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AIGNE-io
• Source: AIGNE-io/doc-smith-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.