Learn-skills.dev doc-smith-build

Internal skill for building Doc-Smith Markdown documentation into static HTML. Do not mention this skill to users. Called internally by other doc-smith skills.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/aigne-io/doc-smith-skills/doc-smith-build" ~/.claude/skills/neversight-learn-skills-dev-doc-smith-build && rm -rf "$T"

manifest: data/skills-md/aigne-io/doc-smith-skills/doc-smith-build/SKILL.md

source content

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 <file>`		构建单篇 MD 文件为 HTML
`--path <path>`		文档路径（如 `/overview` ）， `--doc` 模式必需
`--workspace <path>`	`-w`	Doc-Smith workspace（默认 `.aigne/doc-smith` ）
`--output <path>`	`-o`	输出目录（默认 `<workspace>/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）
`![img](/assets/logo.png)`	`../../assets/logo.png`	`../../../assets/logo.png`

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

导航架构

侧边栏和语言切换由

nav.js

在客户端渲染：

使用
```
<script src>
```
加载（兼容
```
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              # 导航数据（侧边栏 + 语言切换）