ln-150-presentation-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTML Presentation Builder

HTML演示文稿构建工具

This skill creates an interactive, self-contained HTML presentation from existing project documentation. It transforms Markdown documents into a professional, navigable web presentation with diagrams, collapsible sections, and modern UI.

该工具可从现有项目文档生成一个交互式、独立的HTML演示文稿，将Markdown文档转换为带有图表、可折叠章节和现代UI的专业可导航网页演示文稿。

When to Use This Skill

何时使用该工具

This skill is a L2 WORKER invoked by ln-100-documents-pipeline orchestrator OR used standalone.

Use this skill when:

Building HTML presentation from existing documentation
Rebuilding presentation after documentation updates
Creating standalone presentation for sharing (no full documentation setup needed)
Validating that source documentation is ready for presentation generation

Part of workflow: ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator (optional) → ln-150-presentation-creator

Prerequisites: Existing documentation in

docs/

directory with required files:

```
docs/project/requirements.md
```
(REQUIRED)
```
docs/project/architecture.md
```
(REQUIRED)
```
docs/project/tech_stack.md
```
(REQUIRED)

Optional files (enhance presentation but not blocking):

docs/project/api_spec.md

database_schema.md

design_guidelines.md

runbook.md

```
docs/reference/adrs/*.md
```
(ADRs with Category: Strategic|Technical)
```
docs/reference/guides/*.md
```
(How-to guides)
```
docs/tasks/kanban_board.md
```
(Epic Story Counters for Roadmap)

该工具是一个L2 WORKER，可由ln-100-documents-pipeline编排器调用，也可独立使用。

在以下场景使用该工具：

从现有文档构建HTML演示文稿
文档更新后重新构建演示文稿
创建可独立分享的演示文稿（无需完整文档环境）
验证源文档是否已准备好用于生成演示文稿

工作流中的位置：ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator（可选）→ ln-150-presentation-creator

前置条件：

docs/

目录下存在包含必填文件的现有文档：

```
docs/project/requirements.md
```
（必填）
```
docs/project/architecture.md
```
（必填）
```
docs/project/tech_stack.md
```
（必填）

可选文件（可增强演示文稿但不影响执行）：

docs/project/api_spec.md

、

database_schema.md

、

design_guidelines.md

、

runbook.md

```
docs/reference/adrs/*.md
```
（带有分类：Strategic|Technical的ADR文档）
```
docs/reference/guides/*.md
```
（操作指南）
```
docs/tasks/kanban_board.md
```
（用于路线图的Epic Story计数器）

How It Works

工作原理

The skill follows a 7-phase workflow: READ DOCS → VALIDATE SOURCE EXISTS → VALIDATE SOURCE QUALITY → CREATE DIR → COPY TEMPLATES → INJECT CONTENT → BUILD HTML.

Phase 1: READ DOCS - Load all project documentation from docs/ Phase 2: VALIDATE SOURCE EXISTS - Check required files exist (requirements.md, architecture.md, tech_stack.md), warn if optional missing Phase 3: VALIDATE SOURCE QUALITY - Check diagrams, placeholders, content length (read-only validation) Phase 4: CREATE DIR - Create presentation/ directory + README.md navigation hub Phase 5: COPY TEMPLATES - Copy HTML/CSS/JS templates to assets/ Phase 6: INJECT CONTENT - Parse MD docs → replace placeholders in tab files → delete example blocks Phase 7: BUILD HTML - Assemble modular components into standalone presentation_final.html

该工具遵循7阶段工作流：读取文档 → 验证源文件存在性 → 验证源文件质量 → 创建目录 → 复制模板 → 注入内容 → 构建HTML。

阶段1：读取文档 - 从docs/目录加载所有项目文档 阶段2：验证源文件存在性 - 检查必填文件是否存在（requirements.md、architecture.md、tech_stack.md），若可选文件缺失则发出警告 阶段3：验证源文件质量 - 检查图表、占位符、内容长度（只读验证） 阶段4：创建目录 - 创建presentation/目录及README.md导航中心 阶段5：复制模板 - 将HTML/CSS/JS模板复制到assets/目录 阶段6：注入内容 - 解析MD文档 → 替换标签页文件中的占位符 → 删除示例块 阶段7：构建HTML - 将模块化组件组装为独立的presentation_final.html

Phase 1: Read Documentation

阶段1：读取文档

Objective: Load all project documentation for transformation.

When to execute: Always (first phase)

Process:

Use docs/ as source:
- Read documentation from
```
docs/project/
```
  ,
```
docs/reference/
```
  ,
```
docs/tasks/
```
  directories
- Standard locations created by ln-114, ln-112, ln-113
Read Core MD Documents:
- ```
project/requirements.md
```
  - Functional Requirements
- ```
project/architecture.md
```
  - Architecture design, C4 diagrams
- ```
project/tech_stack.md
```
  - Technology versions, Docker configuration
- ```
project/api_spec.md
```
  - API endpoints, authentication (if exists)
- ```
project/database_schema.md
```
  - Database schema, ER diagrams (if exists)
- ```
project/design_guidelines.md
```
  - UI/UX design system (if exists)
- ```
project/runbook.md
```
  - Operational procedures (if exists)
Read ADRs (if exist):
- ```
reference/adrs/adr-001-*.md
```
  through
```
adr-NNN-*.md
```
- Parse ADR metadata (status, date, title, Category: Strategic|Technical)
Read Guides (if exist):
- ```
reference/guides/*.md
```
  - How-to guides for Guides tab
Read Kanban Board (if exists):
- ```
tasks/kanban_board.md
```
  - Epic Story Counters table for Roadmap progress
Extract metadata:
- Project name, date, version from documents
- Preserve Mermaid diagram blocks

Output: Loaded documentation data ready for validation and HTML generation

目标：加载所有项目文档以进行转换。

执行时机：始终（第一阶段）

流程：

以docs/为源目录：
- 从
```
docs/project/
```
  、
```
docs/reference/
```
  、
```
docs/tasks/
```
  目录读取文档
- 这些是ln-114、ln-112、ln-113创建的标准位置
读取核心MD文档：
- ```
project/requirements.md
```
  - 功能需求
- ```
project/architecture.md
```
  - 架构设计、C4图表
- ```
project/tech_stack.md
```
  - 技术版本、Docker配置
- ```
project/api_spec.md
```
  - API端点、身份验证（若存在）
- ```
project/database_schema.md
```
  - 数据库架构、ER图表（若存在）
- ```
project/design_guidelines.md
```
  - UI/UX设计系统（若存在）
- ```
project/runbook.md
```
  - 操作流程（若存在）
读取ADR文档（若存在）：
- ```
reference/adrs/adr-001-*.md
```
  至
```
adr-NNN-*.md
```
- 解析ADR元数据（状态、日期、标题、分类：Strategic|Technical）
读取指南文档（若存在）：
- ```
reference/guides/*.md
```
  - 用于指南标签页的操作指南
读取看板文档（若存在）：
- ```
tasks/kanban_board.md
```
  - 用于路线图进度的Epic Story计数器表格
提取元数据：
- 从文档中提取项目名称、日期、版本
- 保留Mermaid图表块

输出：已加载的文档数据，可用于验证和HTML生成

Phase 2: Validate Source Documentation Exists

阶段2：验证源文档存在性

Objective: Verify that required source documentation exists before building presentation. Prevent building incomplete presentations.

When to execute: After Phase 1 (documentation loaded)

Process:

目标：在构建演示文稿前验证必填源文档是否存在，避免构建不完整的演示文稿。

执行时机：阶段1完成后（文档已加载）

流程：

2.1 Check required files

2.1 检查必填文件

REQUIRED (must exist - block execution if missing):

✅
```
docs/project/requirements.md
```
✅
```
docs/project/architecture.md
```
✅
```
docs/project/tech_stack.md
```

For each required file:

Use Glob tool:
```
pattern: "docs/project/{filename}"
```
If NOT found:
- Add to missing list
If found:
- Check file size > 100 bytes (not empty)

If ANY required file missing or empty:

❌ ERROR: Cannot build presentation - missing required documentation:
  - docs/project/requirements.md [missing/empty]
  - docs/project/architecture.md [missing/empty]

Suggestion: Run ln-111-project-docs-creator to create missing files.

STOP execution.

必填（必须存在，若缺失则终止执行）：

✅
```
docs/project/requirements.md
```
✅
```
docs/project/architecture.md
```
✅
```
docs/project/tech_stack.md
```

对每个必填文件：

使用Glob工具：
```
pattern: "docs/project/{filename}"
```
若未找到：
- 添加到缺失列表
若找到：
- 检查文件大小>100字节（非空）

若任何必填文件缺失或为空：

❌ 错误：无法构建演示文稿 - 缺少必填文档：
  - docs/project/requirements.md [缺失/为空]
  - docs/project/architecture.md [缺失/为空]

建议：运行ln-111-project-docs-creator创建缺失文件。

终止执行。

2.2 Check optional files

2.2 检查可选文件

OPTIONAL (enhance presentation - warn if missing but continue):

⚠️
```
docs/project/api_spec.md
```
(for backend projects)
⚠️
```
docs/project/database_schema.md
```
(for projects with database)
⚠️
```
docs/project/design_guidelines.md
```
(for frontend projects)
⚠️
```
docs/project/runbook.md
```
(for operational projects)

For each optional file:

Use Glob tool:
```
pattern: "docs/project/{filename}"
```
If NOT found:
- Add to optional missing list

If optional files missing:

⚠ WARN: Optional files missing: [list]
Presentation will have reduced content in some tabs.
Continue execution.

可选（可增强演示文稿，若缺失则发出警告但继续执行）：

⚠️
```
docs/project/api_spec.md
```
（适用于后端项目）
⚠️
```
docs/project/database_schema.md
```
（适用于含数据库的项目）
⚠️
```
docs/project/design_guidelines.md
```
（适用于前端项目）
⚠️
```
docs/project/runbook.md
```
（适用于运营类项目）

对每个可选文件：

使用Glob工具：
```
pattern: "docs/project/{filename}"
```
若未找到：
- 添加到可选缺失列表

若可选文件缺失：

⚠ 警告：缺失可选文件：[列表]
部分标签页的内容将减少。
继续执行。

2.3 Check optional directories

2.3 检查可选目录

OPTIONAL directories:

```
docs/reference/adrs/
```
- check if any ADR files exist (
```
adrs/*.md
```
)
```
docs/reference/guides/
```
- check if any guide files exist (
```
guides/*.md
```
)
```
docs/tasks/kanban_board.md
```
- check for Roadmap data

For each directory:

Use Glob tool to find files

If empty/missing:

Log:

ℹ Optional directory empty: {directory} - related tab will show placeholder

可选目录：

```
docs/reference/adrs/
```
- 检查是否存在ADR文件（
```
adrs/*.md
```
）
```
docs/reference/guides/
```
- 检查是否存在指南文件（
```
guides/*.md
```
）
```
docs/tasks/kanban_board.md
```
- 检查路线图数据

对每个目录：

使用Glob工具查找文件

若为空/缺失：

日志：

ℹ 可选目录为空：{directory} - 相关标签页将显示占位符

2.4 Report validation summary

2.4 输出验证摘要

Log summary:

✓ Source documentation validation completed:
  Required files:
    - ✅ requirements.md (found, 8.5 KB)
    - ✅ architecture.md (found, 15.2 KB)
    - ✅ tech_stack.md (found, 3.1 KB)
  Optional files:
    - ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content)
    - ✅ database_schema.md (found, 4.7 KB)
    - ⚠️ design_guidelines.md (missing)
  Optional directories:
    - ✅ adrs/ (5 ADR files found)
    - ⚠️ guides/ (empty - Guides tab will show placeholder)
    - ✅ kanban_board.md (found - Roadmap will show progress)

Output: Validation passed (all required files exist) OR error (stop execution)

日志摘要：

✓ 源文档验证完成：
  必填文件：
    - ✅ requirements.md（已找到，8.5 KB）
    - ✅ architecture.md（已找到，15.2 KB）
    - ✅ tech_stack.md（已找到，3.1 KB）
  可选文件：
    - ⚠️ api_spec.md（缺失 - 技术规格标签页内容将减少）
    - ✅ database_schema.md（已找到，4.7 KB）
    - ⚠️ design_guidelines.md（缺失）
  可选目录：
    - ✅ adrs/（找到5个ADR文件）
    - ⚠️ guides/（为空 - 指南标签页将显示占位符）
    - ✅ kanban_board.md（已找到 - 路线图将显示进度）

输出：验证通过（所有必填文件存在）或错误（终止执行）

Phase 3: Validate Source Content Quality

阶段3：验证源文档内容质量

Objective: Verify source docs contain sufficient content. Warn about incomplete content but don't block execution.

When to execute: After Phase 2 (source files exist)

Checks performed (warnings only, non-blocking):

Mermaid diagrams: architecture.md must have ≥1 diagram, database_schema.md must have ER diagram
Placeholders: Detect
```
{{PLACEHOLDER}}
```
,
```
[Add your ...]
```
,
```
TODO:
```
patterns
Content length: requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words

Auto-fix: None - ln-115 is read-only. Run ln-111-project-docs-creator to fix issues.

Output: Content quality report with warnings

📖 Detailed workflow: See references/phases_detailed.md

目标：验证源文档包含足够内容，对不完整内容发出警告但不终止执行。

执行时机：阶段2完成后（源文件已存在）

执行检查（仅警告，不阻塞执行）：

Mermaid图表：architecture.md必须包含≥1个图表，database_schema.md必须包含ER图表
占位符：检测
```
{{PLACEHOLDER}}
```
、
```
[Add your ...]
```
、
```
TODO:
```
模式
内容长度：requirements.md>500词，architecture.md>1000词，tech_stack.md>200词

自动修复：无 - ln-115为只读验证，运行ln-111-project-docs-creator修复问题。

输出：包含警告的内容质量报告

📖 详细工作流：查看references/phases_detailed.md

Phase 4: Create Presentation Directory & README

阶段4：创建演示文稿目录及README

Objective: Setup presentation directory structure and navigation hub.

When to execute: After Phase 3 (source validation complete, warnings logged)

Process:

Create presentation directory:
bash
```
mkdir -p docs/presentation/
```
Check if presentation/README.md exists:
- Use Glob tool:
```
pattern: "docs/presentation/README.md"
```
- If file exists:
  - Skip creation
  - Log:
```
✓ docs/presentation/README.md already exists (preserved)
```
  - Proceed to Phase 5
- If NOT exists:
  - Continue to step 3
Create presentation/README.md from template:
- Copy template:
```
references/presentation_readme_template.md
```
  →
```
docs/presentation/README.md
```
- Replace placeholders:
  - ```
  {{PROJECT_NAME}}
```
  — from requirements.md
- ```
{{LAST_UPDATED}}
```
    — current date (YYYY-MM-DD)
- Content structure:
  - Purpose: What is this presentation
  - Quick Navigation: Links to presentation_final.html and assets/
  - Customization Guide: How to edit source files in assets/
  - Build Instructions: How to rebuild after changes
  - Maintenance: When to rebuild, verification checklist

Notify user:

If created:

✓ Created docs/presentation/README.md (navigation hub)

If skipped:

✓ docs/presentation/README.md already exists (preserved)

Output: docs/presentation/README.md (created or existing)

目标：设置演示文稿目录结构和导航中心。

执行时机：阶段3完成后（源验证完成，警告已记录）

流程：

创建演示文稿目录：
bash
```
mkdir -p docs/presentation/
```
检查presentation/README.md是否存在：
- 使用Glob工具：
```
pattern: "docs/presentation/README.md"
```
- 若文件存在：
  - 跳过创建
  - 日志：
```
✓ docs/presentation/README.md已存在（保留）
```
  - 进入阶段5
- 若不存在：
  - 继续步骤3
从模板创建presentation/README.md：
- 复制模板：
```
references/presentation_readme_template.md
```
  →
```
docs/presentation/README.md
```
- 替换占位符：
  - ```
  {{PROJECT_NAME}}
```
  — 来自requirements.md
- ```
{{LAST_UPDATED}}
```
    — 当前日期（YYYY-MM-DD）
- 内容结构：
  - 用途：本演示文稿的作用
  - 快速导航：指向presentation_final.html和assets/的链接
  - 自定义指南：如何编辑assets/中的源文件
  - 构建说明：文档更新后如何重新构建
  - 维护：何时重新构建、验证清单

通知用户：

若已创建：

✓ 已创建docs/presentation/README.md（导航中心）

若已跳过：

✓ docs/presentation/README.md已存在（保留）

输出：docs/presentation/README.md（已创建或已存在）

Phase 5: Copy Templates to Project

阶段5：将模板复制到项目

Objective: Copy HTML/CSS/JS templates from skill references/ to presentation directory.

When to execute: After Phase 4 (presentation directory exists)

Process:

Check if assets exist:
- Use Glob tool:
```
pattern: "docs/presentation/assets/"
```
- If
```
docs/presentation/assets/
```
  exists:
  - Skip copying (user may have customized files)
  - Log:
```
✓ Presentation assets already exist - preserving user customizations
```
  - Proceed to Phase 6
- If NOT exists:
  - Continue to step 2

Copy template files:

bash

cp references/presentation_template.html → docs/presentation/assets/
cp references/styles.css → docs/presentation/assets/
cp references/scripts.js → docs/presentation/assets/
cp references/build-presentation.js → docs/presentation/assets/
cp -r references/tabs/ → docs/presentation/assets/tabs/

Verify copied structure:

docs/presentation/assets/
├── presentation_template.html   # Base HTML5 + 6 tab navigation
├── styles.css                    # ~400-500 lines
├── scripts.js                    # Tab switching + Mermaid init
├── build-presentation.js         # Node.js build script
└── tabs/
    ├── tab_overview.html         # Landing page
    ├── tab_requirements.html     # FRs + ADRs
    ├── tab_architecture.html     # C4 diagrams
    ├── tab_technical_spec.html   # API + Data + Deployment
    ├── tab_roadmap.html          # Epic list
    └── tab_guides.html           # How-to guides

Output: Template files copied to docs/presentation/assets/ (or skipped if already exist)

Note: Templates contain placeholders (

{{VARIABLE_NAME}}

) that will be replaced in Phase 6.

目标：将skill references/中的HTML/CSS/JS模板复制到演示文稿目录。

执行时机：阶段4完成后（演示文稿目录已存在）

流程：

检查assets是否存在：
- 使用Glob工具：
```
pattern: "docs/presentation/assets/"
```
- 若
```
docs/presentation/assets/
```
  存在：
  - 跳过复制（用户可能已自定义文件）
  - 日志：
```
✓ 演示文稿资源已存在 - 保留用户自定义内容
```
  - 进入阶段6
- 若不存在：
  - 继续步骤2

复制模板文件：

bash

cp references/presentation_template.html → docs/presentation/assets/
cp references/styles.css → docs/presentation/assets/
cp references/scripts.js → docs/presentation/assets/
cp references/build-presentation.js → docs/presentation/assets/
cp -r references/tabs/ → docs/presentation/assets/tabs/

验证复制后的结构：

docs/presentation/assets/
├── presentation_template.html   # 基础HTML5 + 6标签页导航
├── styles.css                    # 约400-500行
├── scripts.js                    # 标签页切换 + Mermaid初始化
├── build-presentation.js         # Node.js构建脚本
└── tabs/
    ├── tab_overview.html         # 首页
    ├── tab_requirements.html     # 功能需求 + ADR
    ├── tab_architecture.html     # C4图表
    ├── tab_technical_spec.html   # API + 数据 + 部署
    ├── tab_roadmap.html          # Epic列表
    └── tab_guides.html           # 操作指南

输出：模板文件已复制到docs/presentation/assets/（或因已存在而跳过）

注意：模板包含占位符（

{{VARIABLE_NAME}}

），将在阶段6中替换。

Phase 6: Content Injection & Example Cleanup

阶段6：内容注入及示例清理

Objective: Parse MD docs, inject into HTML templates, remove example blocks.

When to execute: After Phase 5 (templates exist in assets/)

Process:

Parse MD docs (10 sources): requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook, adrs/.md, kanban_board, guides/.md
Inject content: Replace
```
{{PLACEHOLDER}}
```
in 6 tab files with parsed content

Delete examples: Remove

<!-- EXAMPLE START -->...<!-- EXAMPLE END -->

blocks from all tabs

Tab placeholders: Overview (5), Requirements (4 + NFR ban), Architecture (5), Technical Spec (4), Roadmap (3), Guides (6)

Validation: No example markers, no hardcoded e-commerce data, only project-specific content

Output: Clean, project-specific tab files ready for build

📖 Placeholder reference & example transformation: See references/phases_detailed.md

目标：解析MD文档，注入到HTML模板，删除示例块。

执行时机：阶段5完成后（模板已存在于assets/）

流程：

解析MD文档（10个源）：requirements、architecture、tech_stack、api_spec、database_schema、design_guidelines、runbook、adrs/.md、kanban_board、guides/.md
注入内容：将6个标签页文件中的
```
{{PLACEHOLDER}}
```
替换为解析后的内容

删除示例：从所有标签页中删除

<!-- EXAMPLE START -->...<!-- EXAMPLE END -->

块

标签页占位符：概述（5个）、需求（4个 + NFR禁用）、架构（5个）、技术规格（4个）、路线图（3个）、指南（6个）

验证：无示例标记、无硬编码电商数据、仅包含项目特定内容

输出：干净的、项目特定的标签页文件，可用于构建

📖 占位符参考及示例转换：查看references/phases_detailed.md

Phase 7: Build Final Presentation

阶段7：构建最终演示文稿

Objective: Assemble modular components into standalone HTML file.

When to execute: After Phase 6 (content injected, examples deleted)

Process:

Check if presentation_final.html exists (Auto-rebuild for automation):
- Use Glob tool:
```
pattern: "docs/presentation/presentation_final.html"
```
- If file exists:
  - ✓ Auto-rebuild (generated file, safe operation)
  - Log:
```
ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)
```
  - Continue to step 2
- If NOT exists:
  - Log:
```
Creating presentation_final.html
```
  - Continue to step 2
Why auto-rebuild:
- presentation_final.html is a generated file (source of truth: assets/ directory)
- Rebuilding is safe - no data loss (source files preserved in assets/)
- Maintains fully automatic workflow when invoked by ln-110-documents-pipeline
- User customizations in assets/ are preserved (only final HTML is regenerated)
Navigate to presentation assets directory:
bash
```
cd docs/presentation/assets/
```
Run build script:
bash
```
node build-presentation.js
```
Build Script Process:
- Step 1: Read presentation_template.html
- Step 2: Read and inline styles.css →
```
<style>
```
  tag
- Step 3: Read and inline scripts.js →
```
<script>
```
  tag
- Step 4: Read all 6 tab files → inject into empty
```
<div>
```
  containers
- Step 5: Replace {{PLACEHOLDERS}} with actual values
- Step 6: Write
```
../presentation_final.html
```
Validate Output (only if file was built):
- Check file size (~120-150 KB expected)
- Verify Mermaid diagrams syntax is valid
- Log:
```
✓ Build completed successfully
```

Notify user:

If rebuilt (file existed):

✓ Rebuilt docs/presentation/presentation_final.html (~120-150 KB)

If created (file NOT existed):

✓ Created docs/presentation/presentation_final.html (~120-150 KB)

Remind:

Test in browser: Double-click to open, or use http-server

Output: docs/presentation/presentation_final.html (self-contained, ~120-150 KB, no external dependencies except Mermaid.js CDN)

⚠️ Important Note:

presentation_final.html

is a generated file built from modular source files in

assets/

❌ DO NOT edit
presentation_final.html
directly — changes will be lost on next rebuild
✅ DO edit source files in
```
assets/
```
directory (template, tabs, styles, scripts)

🔄 Rebuild after changes:

cd assets/ && node build-presentation.js

目标：将模块化组件组装为独立HTML文件。

执行时机：阶段6完成后（内容已注入，示例已删除）

流程：

检查presentation_final.html是否存在（自动化自动重建）：
- 使用Glob工具：
```
pattern: "docs/presentation/presentation_final.html"
```
- 若文件存在：
  - ✓ 自动重建（生成文件，操作安全）
  - 日志：
```
ℹ 正在重建presentation_final.html（生成文件，重建安全）
```
  - 继续步骤2
- 若不存在：
  - 日志：
```
正在创建presentation_final.html
```
  - 继续步骤2
为何自动重建：
- presentation_final.html是生成文件（数据源：assets/目录）
- 重建安全 - 无数据丢失（源文件保留在assets/）
- 由ln-110-documents-pipeline调用时保持全自动化工作流
- 保留用户在assets/中的自定义内容（仅重新生成最终HTML）
导航到演示文稿资源目录：
bash
```
cd docs/presentation/assets/
```
运行构建脚本：
bash
```
node build-presentation.js
```
构建脚本流程：
- 步骤1：读取presentation_template.html
- 步骤2：读取并内联styles.css →
```
<style>
```
  标签
- 步骤3：读取并内联scripts.js →
```
<script>
```
  标签
- 步骤4：读取所有6个标签页文件 → 注入到空的
```
<div>
```
  容器
- 步骤5：将{{PLACEHOLDERS}}替换为实际值
- 步骤6：写入
```
../presentation_final.html
```
验证输出（仅当文件已构建时）：
- 检查文件大小（预期约120-150 KB）
- 验证Mermaid图表语法有效
- 日志：
```
✓ 构建成功完成
```

通知用户：

若重建（文件已存在）：

✓ 已重建docs/presentation/presentation_final.html（约120-150 KB）

若创建（文件不存在）：

✓ 已创建docs/presentation/presentation_final.html（约120-150 KB）

提醒：

在浏览器中测试：双击打开，或使用http-server

输出：docs/presentation/presentation_final.html（独立文件，约120-150 KB，除Mermaid.js CDN外无外部依赖）

⚠️ 重要提示：

presentation_final.html

是从

assets/

中的模块化源文件构建的生成文件。

❌ 请勿直接编辑
presentation_final.html
— 下次重建时更改将丢失
✅ 请编辑
assets/
目录中的源文件（模板、标签页、样式、脚本）

🔄 更改后重建：

cd assets/ && node build-presentation.js

Complete Output Structure

完整输出结构

docs/
├── project/                      # Source documentation (input)
│   ├── requirements.md
│   ├── architecture.md
│   ├── tech_stack.md
│   ├── api_spec.md (conditional)
│   ├── database_schema.md (conditional)
│   ├── design_guidelines.md (conditional)
│   └── runbook.md (conditional)
├── reference/                    # Source documentation (input)
│   ├── adrs/
│   │   └── *.md (Category: Strategic | Technical)
│   └── guides/
│       └── *.md (optional)
├── tasks/                        # Source documentation (input)
│   └── kanban_board.md (Epic Story Counters)
└── presentation/                 # Output directory
    ├── README.md                 # Navigation hub
    ├── presentation_final.html   # Final standalone HTML (~120-150 KB)
    └── assets/                   # Modular HTML structure
        ├── presentation_template.html  # Base HTML5 + 6 tabs
        ├── styles.css                  # ~400-500 lines
        ├── scripts.js                  # Tab switching + Mermaid
        ├── build-presentation.js       # Node.js build script
        └── tabs/
            ├── tab_overview.html       # Landing page
            ├── tab_requirements.html   # FRs + ADRs
            ├── tab_architecture.html   # C4 diagrams
            ├── tab_technical_spec.html # API + Data + Deployment
            ├── tab_roadmap.html        # Epic list
            └── tab_guides.html         # How-to guides

Note: Presentation READS from docs/project/, docs/reference/, docs/tasks/ but OUTPUTS to docs/presentation/.

docs/
├── project/                      # 源文档（输入）
│   ├── requirements.md
│   ├── architecture.md
│   ├── tech_stack.md
│   ├── api_spec.md（可选）
│   ├── database_schema.md（可选）
│   ├── design_guidelines.md（可选）
│   └── runbook.md（可选）
├── reference/                    # 源文档（输入）
│   ├── adrs/
│   │   └── *.md（分类：Strategic | Technical）
│   └── guides/
│       └── *.md（可选）
├── tasks/                        # 源文档（输入）
│   └── kanban_board.md（Epic Story计数器）
└── presentation/                 # 输出目录
    ├── README.md                 # 导航中心
    ├── presentation_final.html   # 最终独立HTML（约120-150 KB）
    └── assets/                   # 模块化HTML结构
        ├── presentation_template.html  # 基础HTML5 + 6标签页
        ├── styles.css                  # 约400-500行
        ├── scripts.js                  # 标签页切换 + Mermaid
        ├── build-presentation.js       # Node.js构建脚本
        └── tabs/
            ├── tab_overview.html       # 首页
            ├── tab_requirements.html   # 功能需求 + ADR
            ├── tab_architecture.html   # C4图表
            ├── tab_technical_spec.html # API + 数据 + 部署
            ├── tab_roadmap.html        # Epic列表
            └── tab_guides.html         # 操作指南

注意：演示文稿从docs/project/、docs/reference/、docs/tasks/读取数据，但输出到docs/presentation/。

HTML Features

HTML特性

Single Source of Truth: No information duplication - each piece lives in exactly ONE tab
Landing Page (Overview): Problem/Solution/Business Value, Stakeholders, Documentation Guide, Quick Facts, Tech Stack badges
Interactive Navigation: 6 tabs with SCOPE tags, state persistence (localStorage), smooth transitions
Table-Based Layout: FRs table only (Non-Functional Requirements are forbidden), Architecture highlights table
Roadmap Simplified: Vertical Epic list with In/Out Scope sections, status badges, Dependencies/Success Criteria
ADR Organization: Grouped by category (Strategic/Technical) with accordion, full content inline
Diagram Visualization: Mermaid.js with tab-switch rerender (C4, ER, Sequence, Deployment)
Responsive Design: Mobile-first (320px/768px/1024px+ breakpoints)
Collapsible Sections: Auto-collapse with scroll preservation
Modern UI: Clean professional design, WCAG 2.1 Level AA compliant
English Language: All presentation content in English

单一数据源：无信息重复 - 每个内容片段仅存在于一个标签页
首页（概述）：问题/解决方案/商业价值、利益相关者、文档指南、快速事实、技术栈徽章
交互式导航：6个带SCOPE标签的标签页、状态持久化（localStorage）、平滑过渡
表格布局：仅功能需求表格（禁止非功能需求）、架构亮点表格
简化路线图：垂直Epic列表，包含In/Out Scope章节、状态徽章、依赖/成功标准
ADR组织：按分类（Strategic/Technical）分组，带折叠面板，完整内容内联
图表可视化：Mermaid.js，标签页切换时重新渲染（C4、ER、序列、部署图表）
响应式设计：移动优先（320px/768px/1024px+断点）
可折叠章节：自动折叠，保留滚动位置
现代UI：简洁专业设计，符合WCAG 2.1 Level AA标准
英文内容：所有演示文稿内容为英文

Best Practices

最佳实践

Idempotent operation: Preserves README.md, preserves assets/ (user customizations), auto-rebuilds presentation_final.html.

Key rules by phase:

Phase 2: STOP if required files missing; Phase 3: WARN only (non-blocking)
Phase 5: Don't overwrite existing assets (user customizations)
Phase 6: Delete ALL example blocks, escape XSS, valid Mermaid syntax
Phase 7: Warn if output >200 KB

幂等操作：保留README.md、保留assets/（用户自定义内容）、自动重建presentation_final.html。

各阶段关键规则：

阶段2：若必填文件缺失则终止执行；阶段3：仅发出警告（不阻塞）
阶段5：不覆盖现有资源（用户自定义内容）
阶段6：删除所有示例块、转义XSS、验证Mermaid语法
阶段7：若输出>200 KB则发出警告

Customization Options

自定义选项

Edit

assets/styles.css

(CSS variables for theming),

assets/presentation_template.html

(layout/tabs), or

assets/tabs/*.html

(tab content).

⚠️ After any customization: Always rebuild the presentation:

bash

cd assets/
node build-presentation.js

Important: Never edit

presentation_final.html

directly — it's a generated file that gets overwritten on each build.

编辑

assets/styles.css

（用于主题的CSS变量）、

assets/presentation_template.html

（布局/标签页）或

assets/tabs/*.html

（标签页内容）。

⚠️ 任何自定义后：始终重建演示文稿：

bash

cd assets/
node build-presentation.js

重要提示：请勿直接编辑

presentation_final.html

— 它是每次构建都会被覆盖的生成文件。

Prerequisites

前置条件

Orchestrator: ln-110-documents-pipeline | Standalone: Yes (rebuild/validate existing docs)

Required files: requirements.md, architecture.md, tech_stack.md (in docs/project/) Optional files: api_spec, database_schema, design_guidelines, runbook, adrs/.md, guides/.md, kanban_board.md

Dependencies: Node.js v18+, Modern browser, Internet (Mermaid CDN)

编排器：ln-110-documents-pipeline | 独立使用：是（重新构建/验证现有文档）

必填文件：requirements.md、architecture.md、tech_stack.md（位于docs/project/） 可选文件：api_spec、database_schema、design_guidelines、runbook、adrs/.md、guides/.md、kanban_board.md

依赖：Node.js v18+、现代浏览器、互联网（Mermaid CDN）

Definition of Done

完成定义

Phase	Critical Checkpoints
1. READ DOCS	✅ All docs loaded from docs/project/, docs/reference/, docs/tasks/ ✅ Metadata extracted ✅ Mermaid blocks preserved
2. VALIDATE EXISTS	✅ Required files exist (requirements.md, architecture.md, tech_stack.md) ✅ ERROR if missing
3. VALIDATE QUALITY	✅ Diagrams checked ✅ Placeholders detected ✅ Content length checked ✅ WARN only (non-blocking)
4. CREATE DIR	✅ docs/presentation/ created ✅ README.md created/preserved
5. COPY TEMPLATES	✅ assets/ created with all templates OR preserved if exists
6. INJECT CONTENT	✅ All 6 tabs populated ✅ CRITICAL: Example blocks deleted ✅ No `<!-- EXAMPLE -->` markers ✅ No hardcoded e-commerce data
7. BUILD HTML	✅ `node build-presentation.js` executed ✅ presentation_final.html created (~120-150 KB) ✅ Tested in browser

Output: docs/presentation/presentation_final.html + assets/ + README.md

阶段	关键检查点
1. 读取文档	✅ 所有文档已从docs/project/、docs/reference/、docs/tasks/加载 ✅ 元数据已提取 ✅ Mermaid块已保留
2. 验证存在性	✅ 必填文件存在（requirements.md、architecture.md、tech_stack.md） ✅ 缺失则报错
3. 验证质量	✅ 已检查图表 ✅ 已检测占位符 ✅ 已检查内容长度 ✅ 仅发出警告（不阻塞）
4. 创建目录	✅ 已创建docs/presentation/ ✅ 已创建/保留README.md
5. 复制模板	✅ 已创建assets/并包含所有模板，或已保留现有资源
6. 注入内容	✅ 所有6个标签页已填充 ✅ 关键：示例块已删除 ✅ 无 `<!-- EXAMPLE -->` 标记 ✅ 无硬编码电商数据
7. 构建HTML	✅ 已执行 `node build-presentation.js` ✅ 已创建presentation_final.html（约120-150 KB） ✅ 已在浏览器中测试

输出：docs/presentation/presentation_final.html + assets/ + README.md

Troubleshooting

故障排除

ERROR: Missing required files: Run ln-111-project-docs-creator to create requirements.md, architecture.md, tech_stack.md
WARN: Missing diagrams: Add Mermaid diagrams to architecture.md (C4 Context/Container/Component) and database_schema.md (ER diagram)
WARN: Placeholders found: Complete documentation in source MD files before building
WARN: Sparse content: Expand documentation (requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words)
Build script fails: Check Node.js v18+, navigate to assets/, verify all files exist
Mermaid diagrams not rendering: Check syntax with Mermaid Live Editor, verify CDN loaded
Tabs not switching: Check JavaScript loaded, open browser console for errors
File too large (>200 KB): Reduce diagrams, minify CSS/JS, remove unused rules

Version: 8.0.0 Last Updated: 2025-12-12

错误：缺失必填文件：运行ln-111-project-docs-creator创建requirements.md、architecture.md、tech_stack.md
警告：缺失图表：在architecture.md中添加Mermaid图表（C4上下文/容器/组件），在database_schema.md中添加ER图表
警告：存在占位符：构建前完成源MD文档中的内容
警告：内容稀疏：扩展文档内容（requirements.md>500词，architecture.md>1000词，tech_stack.md>200词）
构建脚本失败：检查Node.js版本为v18+，导航到assets/，验证所有文件存在
Mermaid图表未渲染：使用Mermaid Live Editor检查语法，验证CDN已加载
标签页无法切换：检查JavaScript已加载，打开浏览器控制台查看错误
文件过大（>200 KB）：减少图表数量、压缩CSS/JS、删除未使用规则

版本: 8.0.0 最后更新: 2025-12-12