B 型 · 文档阅读方案

使用场景

文档阅读模板适合长文本内容的消费和知识沉淀场景，是三层模板中功能最丰富的一层。

不适合的场景

• 结构化数据浏览（搜索+排序+分页 → 用 A 型表格）
• 多类目知识浏览（顶部标签切换 → 用 C 型知识库）
• 协作编辑（B 型是只读展示，不是编辑器）

方案设计

架构

Layer 1: style-guide.css (CSS 变量 + 组件基座)
Layer 2: layout-doc.html (骨架: 侧边栏TOC + 主内容区)
Layer 3: html-gen.py → doc 子命令 (Markdown→HTML 渲染器)

数据流

Markdown 文件 ──→ html-gen doc ──→ 单文件 HTML
                 │                  ├── 自动 TOC
                 │                  ├── 表格渲染
                 │                  ├── 代码高亮
                 │                  ├── 进度条
                 │                  ├── callout 提示框
                 │                  ├── 锚点链接
                 │                  ├── 代码行号
                 │                  └── 外链归档
                 └── 元信息自动计算

关键设计决策

手写 Markdown 渲染器支持语法

# h1  ## h2  ### h3                    — 标题
**bold**  *italic*                      — 行内格式
`code`                                 — 行内代码
``` ```
 代码块                              — 围栏代码块
[link](url)                            — 链接 (target=_blank)
| table | with | cells |               — 表格
- list item                            — 无序列表
1. list item                           — 有序列表
---                                    — 分隔线
> blockquote                           — 引用
> **Note:** text                       — Callout 提示框
> **Warning:** text                    — Callout 警告
> **Tip:** text                        — Callout 提示
> **Danger:** text                     — Callout 危险

行业对标

核心差异：B 型不是文档站框架的替代品，而是「我需要把一个 Markdown 文件发给别人看」场景下的最优解。无需安装、无需构建、无需网络，生成即用。

功能清单

已实现 ✅

待实现 🔜

快速开始

# 从 Markdown 生成文档
html-gen doc -i report.md -o report.html

# 指定标题
html-gen doc -i analysis.md --title "竞品分析报告" -o output.html

# 直接打开
open report.html

命令行参数

html-gen doc -h
  -i, --input FILE   输入 Markdown 文件（必需）
  -o, --output FILE  输出 HTML 文件
  --title TEXT       覆盖文档标题
  --subtitle TEXT    副标题（显示在侧边栏和页头）

URL 入参控制展示设置

打开页面时可追加 URL 参数控制宽度、侧边栏、工具栏等展示设置（知识库 iframe 嵌入时自动附加）：

示例：

# 宽屏 + 隐藏侧边栏/工具栏（知识库嵌入模式）
report.html?width=wide&sidebar=0&toolbar=0

# 窄栏专注阅读
report.html?width=narrow

说明：

• 侧边栏/工具栏隐藏仅控制 display，功能保留（[ 快捷键、搜索等仍可用）
• 知识库（C 型）加载 doc 页时自动附加 sidebar=0&toolbar=0&t=<时间戳>；概述类页面（url 含 overview）额外附加 width=wide
• ?t= 时间戳用于绕过浏览器缓存，与展示参数正交

迭代记录