doc-smith-build

Doc-Smith HTML ビルド

2 つのモードでビルドします。--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

オプション

オプション	エイリアス	説明
--nav		nav.js を生成し、CSS をコピーして、リダイレクトページを作成します
--doc <file>		単一の MD ファイルを HTML にビルドします
--path <path>		ドキュメントのパス（例：/overview）。--doc モードでは必須です
--workspace <path>	-w	Doc-Smith ワークスペース（デフォルトは .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）
	../../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              # 导航数据（侧边栏 + 语言切换）