HTML Presentation Builder

When to Use This Skill

• 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

docs/

• docs/project/requirements.md

  (REQUIRED)

• docs/project/architecture.md

  (REQUIRED)

• docs/project/tech_stack.md

  (REQUIRED)

• 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

Phase 1: Read Documentation

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

Phase 2: Validate Source Documentation Exists

2.1 Check required files

• ✅

  docs/project/requirements.md

• ✅

  docs/project/architecture.md

• ✅

  docs/project/tech_stack.md

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)

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

2.2 Check optional files

• ⚠️

  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)

1. Use Glob tool:

   pattern: "docs/project/{filename}"

2. If NOT found:
   • Add to optional missing list

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

2.3 Check 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

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

✓ 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)

Phase 3: Validate Source Content Quality

1. Mermaid diagrams: architecture.md must have ≥1 diagram, database_schema.md must have ER diagram
2. Placeholders: Detect

   {{PLACEHOLDER}}

   ,

   [Add your ...]

   ,

   TODO:

   patterns
3. Content length: requirements.md >500 words, architecture.md >1000 words, tech_stack.md >200 words

Phase 4: Create Presentation Directory & README

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)

Phase 5: Copy Templates to Project

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

{{VARIABLE_NAME}}

Phase 6: Content Injection & Example Cleanup

1. Parse MD docs (10 sources): requirements, architecture, tech_stack, api_spec, database_schema, design_guidelines, runbook, adrs/.md, kanban_board, guides/.md
2. Inject content: Replace

   {{PLACEHOLDER}}

   in 6 tab files with parsed content
3. Delete examples: Remove

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

   blocks from all tabs

Phase 7: Build Final Presentation

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

presentation_final.html

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

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

• 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

Customization Options

assets/styles.css

assets/presentation_template.html

assets/tabs/*.html

cd assets/
node build-presentation.js

presentation_final.html

Prerequisites

Definition of Done

<!-- EXAMPLE -->

node build-presentation.js

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