786 lines
31 KiB
Markdown
786 lines
31 KiB
Markdown
---
|
||
name: ln-115-presentation-creator
|
||
description: Builds interactive HTML presentation with 6 tabs (Overview, Requirements, Architecture/C4, Tech Spec, Roadmap, Guides). Creates presentation/README.md hub. Worker under ln-110-documents-pipeline.
|
||
---
|
||
|
||
# HTML Presentation Builder
|
||
|
||
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.
|
||
|
||
## When to Use This Skill
|
||
|
||
**This skill is a WORKER** invoked by **ln-110-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-110-documents-pipeline → ln-111-root-docs-creator → ln-112-reference-docs-creator → ln-113-tasks-docs-creator → ln-114-project-docs-creator → **ln-115-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)
|
||
|
||
## 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
|
||
|
||
---
|
||
|
||
## Phase 1: Read Documentation
|
||
|
||
**Objective**: Load all project documentation for transformation.
|
||
|
||
**When to execute**: Always (first phase)
|
||
|
||
**Process**:
|
||
|
||
1. **Use docs/ as source**:
|
||
- Read documentation from `docs/project/`, `docs/reference/`, `docs/tasks/` directories
|
||
- Standard locations created by ln-114, ln-112, ln-113
|
||
|
||
2. **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)
|
||
|
||
3. **Read ADRs** (if exist):
|
||
- `reference/adrs/adr-001-*.md` through `adr-NNN-*.md`
|
||
- Parse ADR metadata (status, date, title, Category: Strategic|Technical)
|
||
|
||
4. **Read Guides** (if exist):
|
||
- `reference/guides/*.md` - How-to guides for Guides tab
|
||
|
||
5. **Read Kanban Board** (if exists):
|
||
- `tasks/kanban_board.md` - Epic Story Counters table for Roadmap progress
|
||
|
||
6. **Extract metadata**:
|
||
- Project name, date, version from documents
|
||
- Preserve Mermaid diagram blocks
|
||
|
||
**Output**: Loaded documentation data ready for validation and HTML generation
|
||
|
||
---
|
||
|
||
## Phase 2: Validate Source Documentation Exists
|
||
|
||
**Objective**: Verify that required source documentation exists before building presentation. Prevent building incomplete presentations.
|
||
|
||
**When to execute**: After Phase 1 (documentation loaded)
|
||
|
||
**Process**:
|
||
|
||
### 2.1 Check required files
|
||
|
||
**REQUIRED** (must exist - block execution if missing):
|
||
- ✅ `docs/project/requirements.md`
|
||
- ✅ `docs/project/architecture.md`
|
||
- ✅ `docs/project/tech_stack.md`
|
||
|
||
For each required file:
|
||
1. Use Glob tool: `pattern: "docs/project/{filename}"`
|
||
2. If NOT found:
|
||
- Add to missing list
|
||
3. 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-114-project-docs-creator to create missing files.
|
||
|
||
STOP execution.
|
||
```
|
||
|
||
### 2.2 Check optional files
|
||
|
||
**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:
|
||
1. Use Glob tool: `pattern: "docs/project/{filename}"`
|
||
2. 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.
|
||
```
|
||
|
||
### 2.3 Check optional directories
|
||
|
||
**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:
|
||
1. Use Glob tool to find files
|
||
2. If empty/missing:
|
||
- Log: `ℹ Optional directory empty: {directory} - related tab will show placeholder`
|
||
|
||
### 2.4 Report validation summary
|
||
|
||
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)
|
||
|
||
---
|
||
|
||
## Phase 3: Validate Source Content Quality
|
||
|
||
**Objective**: Verify that source docs contain sufficient content for presentation generation. Warn about incomplete content but don't block execution.
|
||
|
||
**When to execute**: After Phase 2 (source files exist)
|
||
|
||
**Process**:
|
||
|
||
### 3.1 Check for Mermaid diagrams
|
||
|
||
**Required diagrams:**
|
||
- `architecture.md` MUST have at least 1 Mermaid diagram (preferably C4 Context)
|
||
- `database_schema.md` (if exists) MUST have ER diagram
|
||
|
||
For each file:
|
||
1. Read file content
|
||
2. Search for Mermaid code blocks: ` ```mermaid`
|
||
3. Count diagrams
|
||
|
||
**If diagrams missing:**
|
||
```
|
||
⚠ WARN: Missing diagrams in architecture.md
|
||
Expected: At least 1 Mermaid diagram (C4 Context, Container, or Component)
|
||
Found: 0 diagrams
|
||
|
||
Presentation Architecture tab will have incomplete visualization.
|
||
Suggestion: Add C4 diagrams to architecture.md before building.
|
||
```
|
||
|
||
### 3.2 Check for placeholders
|
||
|
||
**Placeholder patterns to detect:**
|
||
- `{{PLACEHOLDER}}` (template placeholder)
|
||
- `[Add your ...]` (instruction placeholder)
|
||
- `TODO:` (incomplete content marker)
|
||
|
||
For each source file:
|
||
1. Read file content
|
||
2. Search for placeholder patterns (case-insensitive)
|
||
3. Collect matches with line numbers
|
||
|
||
**If placeholders found:**
|
||
```
|
||
⚠ WARN: Source docs contain placeholders:
|
||
- requirements.md:42 - {{PROJECT_DESCRIPTION}}
|
||
- tech_stack.md:15 - [Add your technology rationale]
|
||
- api_spec.md:8 - TODO: Add authentication endpoints
|
||
|
||
Presentation will show incomplete content.
|
||
Suggestion: Complete placeholders before building for professional result.
|
||
```
|
||
|
||
### 3.3 Check content length
|
||
|
||
**Minimum expected lengths:**
|
||
- `requirements.md` > 500 words
|
||
- `architecture.md` > 1000 words
|
||
- `tech_stack.md` > 200 words
|
||
|
||
For each file:
|
||
1. Read file content
|
||
2. Count words (split by whitespace, exclude code blocks)
|
||
3. Compare to threshold
|
||
|
||
**If content too short:**
|
||
```
|
||
⚠ WARN: Sparse content detected:
|
||
- requirements.md: 320 words (expected >500)
|
||
- tech_stack.md: 150 words (expected >200)
|
||
|
||
Presentation may look incomplete with thin content.
|
||
Suggestion: Expand documentation before building.
|
||
```
|
||
|
||
### 3.4 Auto-fix opportunities
|
||
|
||
**None** - ln-115 is **read-only** for source docs:
|
||
- ❌ Does NOT edit markdown documentation
|
||
- ✅ Only READS and TRANSFORMS to HTML
|
||
|
||
**If issues found:**
|
||
```
|
||
💡 To fix content issues:
|
||
- Run ln-114-project-docs-creator to complete documentation
|
||
- Manually edit source files in docs/project/
|
||
- Re-run ln-115-presentation-creator after fixes
|
||
```
|
||
|
||
### 3.5 Report content quality summary
|
||
|
||
Log summary:
|
||
```
|
||
✓ Content quality validation completed:
|
||
Diagrams:
|
||
- ✅ architecture.md: 3 Mermaid diagrams found (C4 Context, Container, Component)
|
||
- ⚠️ database_schema.md: No ER diagram found
|
||
Placeholders:
|
||
- ⚠️ Found 2 placeholders in 2 files (see details above)
|
||
Content length:
|
||
- ✅ requirements.md: 1,250 words
|
||
- ✅ architecture.md: 2,100 words
|
||
- ⚠️ tech_stack.md: 180 words (expected >200)
|
||
|
||
Warnings: 3 (non-blocking)
|
||
Recommendation: Address warnings for professional result, or continue with current content.
|
||
```
|
||
|
||
**Output**: Content quality report (warnings only, does not block execution)
|
||
|
||
---
|
||
|
||
## Phase 4: Create Presentation Directory & README
|
||
|
||
**Objective**: Setup presentation directory structure and navigation hub.
|
||
|
||
**When to execute**: After Phase 3 (source validation complete, warnings logged)
|
||
|
||
**Process**:
|
||
|
||
1. **Create presentation directory**:
|
||
```bash
|
||
mkdir -p docs/presentation/
|
||
```
|
||
|
||
2. **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
|
||
|
||
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
|
||
|
||
4. **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)
|
||
|
||
---
|
||
|
||
## Phase 5: Copy Templates to Project
|
||
|
||
**Objective**: Copy HTML/CSS/JS templates from skill references/ to presentation directory.
|
||
|
||
**When to execute**: After Phase 4 (presentation directory exists)
|
||
|
||
**Process**:
|
||
|
||
1. **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
|
||
|
||
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/
|
||
```
|
||
|
||
3. **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.
|
||
|
||
---
|
||
|
||
## Phase 6: Content Injection & Example Cleanup
|
||
|
||
**Objective**: Parse MD documentation, inject into HTML templates, and remove example blocks to create project-specific presentation.
|
||
|
||
**When to execute**: After Phase 5 (templates exist in assets/)
|
||
|
||
**Process**:
|
||
|
||
### 6.1 Read and Parse MD Documents
|
||
|
||
Read and parse the following documentation files (from Phase 1):
|
||
|
||
1. **requirements.md**: Project name, tagline, business goal, functional requirements, constraints, success criteria
|
||
2. **architecture.md**: Architecture diagrams (C4 Context/Container/Component), solution strategy, quality attributes
|
||
3. **tech_stack.md**: Technology Stack table (with versions, rationale, ADR links), Docker configuration
|
||
4. **api_spec.md** (if exists): API endpoints, authentication methods, error codes
|
||
5. **database_schema.md** (if exists): ER diagrams, data dictionary (tables/columns/types)
|
||
6. **design_guidelines.md** (if exists): Typography, colors, component library, accessibility
|
||
7. **runbook.md** (if exists): Development setup, deployment procedures, troubleshooting
|
||
8. **adrs/*.md**: All ADR files (parse title, status, category, content)
|
||
9. **kanban_board.md** (if exists): Epic Story Counters table for Roadmap progress
|
||
10. **guides/*.md** (if exist): How-to guides for Guides tab
|
||
|
||
### 6.2 Inject Content into Templates
|
||
|
||
Replace placeholders in copied template files with parsed content from project documentation.
|
||
|
||
**Key Placeholders (in tab templates):**
|
||
|
||
**Overview Tab** (`tab_overview.html`):
|
||
- `{{PROJECT_SUMMARY}}` — Problem/Solution/Business Value structure (3 sections)
|
||
- `{{TECH_STACK}}` — Technology badges (brief list only)
|
||
- `{{STAKEHOLDERS}}` — Stakeholder cards with names and roles
|
||
- `{{QUICK_FACTS}}` — Project Status, Total Epics, Deployment Model, Target Platforms
|
||
- `{{NAVIGATION_GUIDE}}` — Documentation guide with tab descriptions
|
||
|
||
**Requirements Tab** (`tab_requirements.html`):
|
||
- `{{FUNCTIONAL_REQUIREMENTS}}` — FRs table (ID, Priority, Requirement, Acceptance Criteria)
|
||
- `{{ADR_STRATEGIC}}` — Strategic ADRs grouped section with accordion
|
||
- `{{ADR_TECHNICAL}}` — Technical ADRs grouped section with accordion
|
||
- `{{SUCCESS_CRITERIA}}` — Project success metrics
|
||
- **Non-Functional Requirements are banned**: Drop any NFR content found in source docs instead of converting it into tables or IDs
|
||
|
||
**Architecture Tab** (`tab_architecture.html`):
|
||
- `{{C4_CONTEXT}}` — System Context diagram (C4 Level 1)
|
||
- `{{C4_CONTAINER}}` — Container diagram (C4 Level 2)
|
||
- `{{C4_COMPONENT}}` — Component diagram (C4 Level 3)
|
||
- `{{DEPLOYMENT_DIAGRAM}}` — Infrastructure deployment diagram
|
||
- `{{ARCHITECTURE_NOTES}}` — Key architecture highlights table
|
||
|
||
**Technical Spec Tab** (`tab_technical_spec.html`):
|
||
- `{{TECH_STACK_TABLE}}` — Full technology stack table with versions and purposes
|
||
- `{{API_ENDPOINTS}}` — API endpoints tables (Authentication, Products, Cart, etc.)
|
||
- `{{DATA_MODELS}}` — ER diagram + Data dictionary table
|
||
- `{{TESTING_STRATEGY}}` — Risk-Based Testing approach and test pyramid
|
||
|
||
**Roadmap Tab** (`tab_roadmap.html`):
|
||
- `{{EPIC_CARDS}}` — All Epic cards with In/Out Scope, Dependencies, Success Criteria, Progress
|
||
- `{{OUT_OF_SCOPE_ITEMS}}` — Project-level out-of-scope items with reasons
|
||
- `{{ROADMAP_LEGEND}}` — Status badges explanation
|
||
|
||
**Guides Tab** (`tab_guides.html`):
|
||
- `{{GETTING_STARTED}}` — Prerequisites, Installation, Verification
|
||
- `{{HOW_TO_GUIDES}}` — Step-by-step how-to guides (from guides/*.md)
|
||
- `{{BEST_PRACTICES}}` — Code style, Testing approach, Design patterns
|
||
- `{{TROUBLESHOOTING}}` — Common problems and solutions
|
||
- `{{CONTRIBUTING}}` — Contributing guidelines
|
||
- `{{EXTERNAL_RESOURCES}}` — Links to external documentation
|
||
|
||
**Placeholder Replacement Logic:**
|
||
- Use **Edit** tool to replace `{{PLACEHOLDER}}` → actual content from project docs
|
||
- For lists/arrays: generate HTML dynamically (e.g., loop through ADRs, create `<details>` elements)
|
||
- For Kanban: parse kanban_board.md → calculate progress % → generate Epic card HTML
|
||
- Preserve SCOPE tags in tab files (HTML comments at top)
|
||
- Escape special characters to prevent XSS
|
||
- Generate valid Mermaid syntax
|
||
|
||
### 6.3 Delete Example Blocks
|
||
|
||
**CRITICAL**: Remove all example content blocks to create project-specific presentation.
|
||
|
||
**Process**:
|
||
1. **Search for example markers** in all 6 tab files:
|
||
- Look for `<!-- EXAMPLE START: Remove this block after replacing placeholder -->`
|
||
- Look for `<!-- EXAMPLE END -->`
|
||
|
||
2. **Delete example blocks** using Edit tool:
|
||
- Remove everything between `<!-- EXAMPLE START -->` and `<!-- EXAMPLE END -->` (inclusive)
|
||
- Do this for ALL occurrences across all 6 tab files
|
||
- Leave only the actual project content that replaced `{{PLACEHOLDER}}` comments
|
||
|
||
3. **Validate cleanup**:
|
||
- ✅ NO `<!-- EXAMPLE START -->` markers should remain
|
||
- ✅ NO `<!-- EXAMPLE END -->` markers should remain
|
||
- ✅ NO hardcoded e-commerce examples (John Smith, React 18 badges, Stripe, etc.)
|
||
- ✅ Only actual project data should be visible in tab files
|
||
|
||
**Example transformation:**
|
||
|
||
**Before (dual-content template):**
|
||
```html
|
||
<!-- PLACEHOLDER: {{PROJECT_SUMMARY}} -->
|
||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||
<div class="project-summary">
|
||
<h3>The Problem</h3>
|
||
<p>Traditional e-commerce platforms struggle...</p>
|
||
</div>
|
||
<!-- EXAMPLE END -->
|
||
```
|
||
|
||
**After Step 6.2 (placeholder replaced):**
|
||
```html
|
||
<div class="project-summary">
|
||
<h3>The Problem</h3>
|
||
<p>Our healthcare system needs unified patient records...</p>
|
||
</div>
|
||
<!-- EXAMPLE START: Remove this block after replacing placeholder -->
|
||
<div class="project-summary">
|
||
<h3>The Problem</h3>
|
||
<p>Traditional e-commerce platforms struggle...</p>
|
||
</div>
|
||
<!-- EXAMPLE END -->
|
||
```
|
||
|
||
**After Step 6.3 (examples deleted):**
|
||
```html
|
||
<div class="project-summary">
|
||
<h3>The Problem</h3>
|
||
<p>Our healthcare system needs unified patient records...</p>
|
||
</div>
|
||
```
|
||
|
||
**Output**: Clean, project-specific tab files with NO example content, ready for build
|
||
|
||
---
|
||
|
||
## Phase 7: Build Final Presentation
|
||
|
||
**Objective**: Assemble modular components into standalone HTML file.
|
||
|
||
**When to execute**: After Phase 6 (content injected, examples deleted)
|
||
|
||
**Process**:
|
||
|
||
1. **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)
|
||
|
||
2. **Navigate to presentation assets directory**:
|
||
```bash
|
||
cd docs/presentation/assets/
|
||
```
|
||
|
||
3. **Run build script**:
|
||
```bash
|
||
node build-presentation.js
|
||
```
|
||
|
||
4. **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`
|
||
|
||
5. **Validate Output** (only if file was built):
|
||
- Check file size (~120-150 KB expected)
|
||
- Verify Mermaid diagrams syntax is valid
|
||
- Log: `✓ Build completed successfully`
|
||
|
||
6. **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`
|
||
|
||
---
|
||
|
||
## 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/.
|
||
|
||
---
|
||
|
||
## HTML Features
|
||
|
||
- **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
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
### Idempotent Operation
|
||
- ✅ Checks file existence before creation (presentation/README.md)
|
||
- ✅ Auto-rebuild: Always rebuilds presentation_final.html (generated file)
|
||
- ✅ Assets preservation: Skips copying templates if assets/ exists (preserves customizations)
|
||
- ✅ Safe re-runs: Can invoke multiple times without data loss
|
||
|
||
### During Documentation Reading (Phase 1)
|
||
- Validate paths: Check docs/ exists before reading
|
||
- Graceful degradation: Continue if some files missing (warn user)
|
||
- Extract metadata: Pull project name, date, version
|
||
- Parse Mermaid blocks: Preserve diagram syntax
|
||
|
||
### During Source Validation (Phase 2/3)
|
||
- **Phase 2**: STOP execution if required files missing (requirements.md, architecture.md, tech_stack.md)
|
||
- **Phase 3**: WARN about quality issues but don't block (missing diagrams, placeholders, sparse content)
|
||
- Provide actionable suggestions: "Run ln-114 to complete docs"
|
||
- Read-only: Never edit source docs
|
||
|
||
### During Template Copying (Phase 5)
|
||
- Check existing assets: Don't overwrite user-customized templates
|
||
- Verify directory structure: Ensure tabs/ subdirectory created
|
||
- Preserve permissions: Maintain executable permissions for build script
|
||
|
||
### During Content Injection & Cleanup (Phase 6)
|
||
- Preserve Markdown formatting: Convert MD → HTML correctly
|
||
- Generate valid Mermaid syntax: Test all diagram syntax
|
||
- Escape special characters: Prevent XSS vulnerabilities
|
||
- Use semantic HTML: Proper heading hierarchy, ARIA labels
|
||
- Preserve SCOPE tags: Keep HTML comments in tab files
|
||
- **Complete example cleanup**: Ensure ALL example blocks deleted
|
||
- **Verify project-specific content**: NO hardcoded e-commerce examples in final tabs
|
||
|
||
### During Build (Phase 7)
|
||
- Validate Node.js availability: Check `node --version` before running
|
||
- Handle errors gracefully: Provide clear error messages
|
||
- Test output: Open presentation_final.html to verify rendering
|
||
- Size check: Warn if file >200 KB (may indicate issues)
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
**Orchestrator**: ln-110-documents-pipeline (invokes this worker in final step)
|
||
|
||
**Standalone usage**: Can also be invoked directly for:
|
||
- Rebuilding HTML presentation after documentation updates
|
||
- Creating standalone presentation for existing docs
|
||
- Validating source documentation readiness
|
||
|
||
**Source Documentation Requirements**:
|
||
- **Required files** (must exist):
|
||
- docs/project/requirements.md
|
||
- docs/project/architecture.md
|
||
- docs/project/tech_stack.md
|
||
- **Optional files** (enhance presentation):
|
||
- docs/project/api_spec.md, database_schema.md, design_guidelines.md, runbook.md
|
||
- docs/reference/adrs/*.md (with Category field)
|
||
- docs/reference/guides/*.md
|
||
- docs/tasks/kanban_board.md
|
||
|
||
**Quality Recommendations** (warnings only, not blocking):
|
||
- architecture.md should have Mermaid diagrams (C4 Context/Container/Component)
|
||
- database_schema.md should have ER diagram
|
||
- Source docs should NOT contain placeholders (`{{PLACEHOLDER}}`, `[Add your...]`)
|
||
- Minimum content length: requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words
|
||
|
||
**Dependencies**:
|
||
- Node.js v18+ (for build-presentation.js)
|
||
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
|
||
- Internet connection (Mermaid.js CDN, optional)
|
||
|
||
**Idempotent**: Yes - can be invoked multiple times without side effects:
|
||
- Preserves existing README.md
|
||
- Preserves existing assets/ (user customizations)
|
||
- Always rebuilds presentation_final.html (generated file)
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
---
|
||
|
||
## Example Usage
|
||
|
||
User: "Build HTML presentation"
|
||
|
||
Process:
|
||
1. **READ DOCS** - Load documentation from docs/project/, docs/reference/, docs/tasks/
|
||
2. **VALIDATE SOURCE EXISTS** - Check requirements.md, architecture.md, tech_stack.md exist (ERROR if missing)
|
||
3. **VALIDATE SOURCE QUALITY** - Check diagrams, placeholders, content length (WARN if issues, but continue)
|
||
4. **CREATE DIR** - Create docs/presentation/ + README.md navigation hub
|
||
5. **COPY TEMPLATES** - Copy HTML/CSS/JS templates to assets/ (or preserve existing)
|
||
6. **INJECT CONTENT** - Parse MD docs → replace placeholders in tabs → delete example blocks
|
||
7. **BUILD HTML** - Assemble modular components → standalone presentation_final.html (~120-150 KB)
|
||
|
||
Output: docs/presentation/presentation_final.html (6 tabs: Overview, Requirements, Architecture, Technical Spec, Roadmap, Guides) + docs/presentation/README.md (navigation hub) + docs/presentation/assets/ (modular source files)
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
- **ERROR: Missing required files**: Run ln-114-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
|
||
|
||
---
|
||
|
||
## Technical Details
|
||
|
||
**Standards**: HTML5, CSS3 (Flexbox/Grid/Variables), ES6+, WCAG 2.1 Level AA, Mobile-first responsive design, Progressive enhancement, Mermaid.js v11
|
||
|
||
**Dependencies**:
|
||
- Node.js v18+ (build script)
|
||
- Modern browser (Chrome/Firefox/Safari/Edge last 2 versions)
|
||
- Internet connection (Mermaid.js CDN, optional)
|
||
|
||
**Language**: English only (all presentation content)
|
||
|
||
---
|
||
|
||
**Version:** 7.0.0 (MAJOR: Added Phase 2/3 validation (source docs existence + content quality). Removed ln-120-docs-validator references. Renumbered phases (2-5 → 4-7). Unified READ+VALIDATE+CREATE workflow. Read-only source validation.)
|
||
**Last Updated:** 2025-11-18
|