# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-aigne-io-doc-smith-skills-doc-smith-build`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AIGNE-io](https://agentstack.voostack.com/s/aigne-io)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [AIGNE-io](https://github.com/AIGNE-io)
- **Source:** https://github.com/AIGNE-io/doc-smith-skills/tree/main/skills/doc-smith-build

## Install

```sh
agentstack add skill-aigne-io-doc-smith-skills-doc-smith-build
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Doc-Smith HTML 构建

双模式构建：`--nav` 生成导航和静态资源，`--doc` 构建单篇文档。

## 用法

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

### 依赖未安装

如果执行脚本时出现模块找不到的错误，需要先安装依赖：

```bash
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](https://github.com/AIGNE-io)
- **Source:** [AIGNE-io/doc-smith-skills](https://github.com/AIGNE-io/doc-smith-skills)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aigne-io-doc-smith-skills-doc-smith-build
- Seller: https://agentstack.voostack.com/s/aigne-io
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.