Skip to content
LiveNew tools this week
Submit
AIMarketly
doc-smith-build logo

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.

NeverSight/skills_feed0installs214stars

SKILL.md

Full skill instructions

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

选项

OptionAliasDescription
--nav生成 nav.js、复制 CSS、创建重定向页面
--doc <file>构建单篇 MD 文件为 HTML
--path <path>文档路径（如 /​overview），--doc 模式必需
--workspace <path>-wDoc-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（页面内联）
  • 处理图片占位符（<!-- afs:image ... -->）
  • /​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              # 导航数据（侧边栏 + 语言切换）