doc-smith-build

Doc-Smith HTML Build

Dual-mode build:--nav Generate navigation and static assets,--doc Build a single document.

Usage

# 生成 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

Options

Option	Alias	Description
--nav		Generate nav.js, copy CSS, create redirect pages
--doc <file>		Build a single MD file as HTML
--path <path>		Document path (e.g. /overview），--doc required for mode
--workspace <path>	-w	Doc-Smith workspace (default .aigne/doc-smith）
--output <path>	-o	Output directory (default <workspace>/dist）

Mode Description

--nav mode

From document-structure.yaml + config.yaml generate navigation data and static assets.

Output:

• assets/nav.js — navigation data (window.__DS_NAV__ = {...}), drives the sidebar and language switching
• assets/docsmith.css — built-in base styles
• assets/theme.css — user theme (creates an empty file if it does not exist)
• index.html — root redirect
• {lang}/index.html — language redirect

When to call: At initialization, after document structure changes.

--doc mode

Build a single MD file as a complete HTML page.

Input: MD file path + document path Output: dist/{lang}/docs/{path}.html

Responsibilities:

• Markdown → HTML conversion (markdown-it)
• Wrap in HTML skeleton (data-ds anchors)
• Generate TOC (inlined in the page)
• Handle image placeholders (<!-- afs:image ... -->）
• /assets/ paths converted to relative paths (see path contract below)
• Concatenate static asset references (CSS + nav.js)

Not responsible for: Navigation rendering (done client-side by nav.js), MD cleanup (handled by the caller).

Path Contract

MD files use /assets/ absolute paths to reference assets; build.mjs automatically converts them to relative paths:

Written in MD	HTML output (depth=1)	HTML output (depth=2)
	../../assets/logo.png	../../../assets/logo.png

• Paths containing .. are considered invalid and are not converted (prevents traversal attacks)
• Old format ../../assets/ is still handled by existing logic (backward compatible)
• External URLs are unaffected

Navigation Architecture

The sidebar and language switching are rendered client-side by nav.js :

• Load using <script src> (compatible with file:// and http:// protocols)
• Updating the document structure only requires regenerating nav.js, with no need to rebuild all HTML pages
• The TOC is still generated inline at build time (page-specific content)

Error Handling

Error Type	Handling
workspace does not exist	Report a clear error
document-structure.yaml missing	Report a clear error
MD file does not exist	Report a clear error
--doc missing --path	Report a clear error
Dependencies not installed	Run in the scripts directory npm install

Dependencies Not Installed

If a module-not-found error occurs when running the script, dependencies need to be installed first:

cd skills/doc-smith-build/scripts && npm install

Output Structure

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