Doc smith build

Skill AIGNE-io/doc-smith-skills/skills/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.From its SKILL.md

Install

npx -y skills add AIGNE-io/doc-smith-skills --skill doc-smith-build

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.0 KB, as published. Nobody here has run it

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              # 导航数据（侧边栏 + 语言切换）