zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
37774aa93778d333e868aca98e2fc8b65118cdcb
gh-levnikolaevich-claude-co…/skills/ln-115-presentation-creator/SKILL.md
Zhongwei Li 37774aa937 Initial commit
2025-11-30 08:37:27 +08:00

31 KiB
Raw Blame History

name, description
name description
ln-115-presentation-creator 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:

    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:

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

<!-- 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):

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

<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:

    cd docs/presentation/assets/

  3. Run build script:

    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:

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

Reference in New Issue View Git Blame Copy Permalink