html-presentations

HTML Presentations

Convert a markdown spec file into an HTML presentation using the Poimandres-themed template.

Files

• Template: {SKILLBASE}/template/index.html
• Example spec: {SKILLBASE}/examples/spec.md
• Build script: {SKILLBASE}/scripts/create_standalone.sh

Instructions

1. Read the spec markdown file (e.g., spec.md)

2. Read the template at {SKILLBASE}/template/index.html

3. Parse the spec file:

   • Split on * * * to get individual slides
   • # Title = title slide (use <h1>)
   • ## Heading = slide heading (use <h2>)
   • - item = bullet list (use <ul><li>)
   • **bold** = emphasis (use <span class="accent"> or <span class="green">)
   • > quote = blockquote (use <blockquote class="quote">)
   • <img src="..."> = image (keep as-is, add class="shadow" if appropriate)
   • ```mermaid ``` = mermaid diagram (wrap in <div class="mermaid-wrapper"><pre class="mermaid">)
   • <!-- image gallery - VERTICAL --> = split images into separate slides (one per slide)
   • <!-- comment --> = other layout hints (e.g., <!-- big quote -->)

4. Generate HTML slides:

   • Each slide is a <section class="slide"> (add centered class for title/image slides)
   • Preserve the template's head section (styles, scripts, mermaid config)
   • Preserve the navigation and script at the bottom

5. Write output to index.html in the same directory as the spec, offer to open it using Bash for the user

6. OPTIONAL Create standalone shareable HTML:

   • Run the build script to embed all PNG images as base64 data URIs
   • Output: FOLDERNAME-standalone.html (e.g., 2026-01-05-luciq-presentation-standalone.html)
   • Creates a single self-contained file (~2-3MB) that opens in any browser

   {SKILLBASE}/scripts/create_standalone.sh /path/to/presentation/folder
   

Slide Type Examples

Title Slide

<section class="slide centered">
  <h1>Presentation Title</h1>
  <p class="subtitle">Subtitle here</p>
</section>

Bullet Points

<section class="slide">
  <h2>Slide Title</h2>
  <ul>
    <li>Point with <span class="accent">emphasis</span></li>
    <li>Another point</li>
  </ul>
</section>

Big Quote

<section class="slide centered">
  <blockquote class="quote">
    "The quote text here"
  </blockquote>
</section>

Mermaid Diagram

<section class="slide centered">
  <h2>Diagram Title</h2>
  <div class="mermaid-wrapper">
    <pre class="mermaid">
graph LR
    A[Start] --> B[End]
    </pre>
  </div>
</section>

Image

<section class="slide centered">
  <h2>Image Title</h2>
  <img src="./image.png" alt="Description" class="shadow" />
</section>

Image Gallery (2 images side by side)

<section class="slide">
  <h2>Gallery Title</h2>
  <div class="columns">
    <div class="column">
      <p class="muted">Caption 1</p>
      <img src="./image1.png" alt="Image 1" />
    </div>
    <div class="column">
      <p class="muted">Caption 2</p>
      <img src="./image2.png" alt="Image 2" />
    </div>
  </div>
</section>

Vertical Image Gallery (one image per slide)

When spec contains <!-- image gallery - VERTICAL -->, split each image into its own slide:

<section class="slide centered">
  <h2>Section Title</h2>
  <p class="muted">Caption 1</p>
  <img src="./image1.png" alt="Image 1" class="shadow" style="max-height: 55vh;" />
</section>

<section class="slide centered">
  <h2>Section Title</h2>
  <p class="muted">Caption 2</p>
  <img src="./image2.png" alt="Image 2" class="shadow" style="max-height: 55vh;" />
</section>

Available CSS Classes

Slide Classes

• .slide - base slide
• .slide.centered - center content
• .slide.top - align to top

Color Classes

• .accent - light blue (#ADD7FF)
• .green - mint green (#5DE4c7)
• .yellow - soft yellow (#fffac2)
• .pink - pink (#d0679d)
• .cyan - cyan (#89ddff)
• .muted - dim gray

Layout Classes

• .columns - two-column grid
• .split - image + text side by side
• .gallery - flex gallery for multiple images

Element Classes

• .subtitle - smaller subtitle text
• .small - smaller text
• .quote - styled blockquote
• .big-number - large stat/number
• .badge - tag/badge element
• .reveal - progressive reveal item (use with data-progressive)

Progressive Reveal

Add data-progressive to a slide to reveal content one item at a time on advance.

How it works:

• Slide starts with title visible, all <li> and .reveal elements hidden
• Each advance (→, Space, or Next button) reveals the next item
• When all items are visible, next advance goes to the next slide
• Going back shows previous slide with all items visible

Note: Progressive slides use padding-top: 15vh instead of vertical centering to prevent layout shift as items reveal.

Progressive Bullet Points

<section class="slide" data-progressive>
  <h2>Key Points</h2>
  <ul>
    <li>First point (revealed on first advance)</li>
    <li>Second point (revealed on second advance)</li>
    <li>Third point (revealed on third advance)</li>
  </ul>
</section>

Progressive Custom Elements

Use .reveal class for non-list items:

<section class="slide centered" data-progressive>
  <h2>Before & After</h2>
  <div class="reveal">
    <p class="muted">Before</p>
    <div class="mermaid-wrapper">
      <pre class="mermaid">graph LR; A-->B</pre>
    </div>
  </div>
  <div class="reveal">
    <p class="muted">After</p>
    <div class="mermaid-wrapper">
      <pre class="mermaid">graph LR; A-->B-->C-->D</pre>
    </div>
  </div>
  <p class="reveal muted">Summary text revealed last</p>
</section>

Progressive Image Gallery

<section class="slide centered" data-progressive>
  <h2>Feature Walkthrough</h2>
  <div style="display: flex; gap: 30px; justify-content: center;">
    <div class="reveal" style="text-align: center;">
      <p class="muted">Step 1</p>
      <img src="./step1.png" class="shadow" />
    </div>
    <div class="reveal" style="text-align: center;">
      <p class="muted">Step 2</p>
      <img src="./step2.png" class="shadow" />
    </div>
    <div class="reveal" style="text-align: center;">
      <p class="muted">Step 3</p>
      <img src="./step3.png" class="shadow" />
    </div>
  </div>
</section>