md-to-cuhk-slides

name	md-to-cuhk-slides
description	Convert any outline-style Markdown file into a self-contained CUHK-themed HTML slide deck. Two steps — (1) generate a reviewable slide plan, (2) render the plan to a single-file HTML presentation. Use when the user asks to "make slides", "generate a presentation from markdown", "convert outline to slides", or mentions the CUHK template.

Markdown → CUHK Slides

Convert any outline-style Markdown document into a self-contained HTML slide deck using the CUHK theme. This is a two-step process: first generate a slide plan markdown that the user can review and edit, then generate the final HTML from that plan.

The skill is general-purpose: the source .md can be a course lecture, a talk, a project pitch, a thesis proposal, or any other outline-style document.

Input

The user provides a path to a .md file. If they do not specify one, look for a single *.md in the current working directory; if there is exactly one candidate, use it, otherwise ask which file to use.

Process Overview

Source .md → [Step 1] → Slide Plan .md → [Step 2] → Final HTML

Step 1 produces a human-readable slide plan markdown that the user can review and edit. Step 2 converts the approved plan into the final self-contained HTML presentation.

By default, execute both steps in sequence. If the user already has a slide plan .md (with the format described below), skip Step 1 and go directly to Step 2.

---

Step 1: Generate the Slide Plan Markdown

1.1 Read the Source Markdown

Read the source .md file. Parse its structure:

• # H1 = presentation title (use the line immediately after # H1, whether it is ## H2 or a paragraph, as the subtitle if present)
• --- (horizontal rules) = section boundaries
• ## H2 = section titles (these become section-slide headers)
• ### H3 = content-slide titles within a section
• #### H4 = sub-headings within a content slide
• Bullet lists, numbered lists, blockquotes, tables, code blocks, images = slide content
• Bold text **...** = emphasized terms

1.2 Plan Each Slide

For each slide, determine:

• Type: which slide type to use
• Layout: which content layout pattern to apply
• Background: which background variant
• Animations: which reveal animations for each element
• Decorations: which decorative elements to include
• Content: what text/data goes on this slide

1.3 Available Slide Types

Reference assets/cuhk-template.html for exact HTML/CSS implementation.

Slide Type	Class	Background	When to Use
Title	title-slide noise	Dark (#2A1533)	First slide only. Orbs, CUHK logo, title, subtitle, author
Outline	content-slide	White (#FAFAF8)	Second slide. Clickable agenda list linking to sections
Section Header	section-slide noise	Purple gradient	Start of each major section. Large number, title, description
Content	content-slide	White (#FAFAF8)	Default content slide
Content Warm	content-slide warm	Cream (#F5F2ED)	Alternate with default for visual rhythm
Quote	quote-slide noise	Cream (#F5F2ED)	Key quotes / insights. Drop-cap, centered text
Split / Comparison	(uses split-panel)	Left=cream, Right=dark	Comparisons, pros/cons, VS badge
End	end-slide noise	Dark (#2A1533)	Last slide. Orbs, CUHK logo, "Thank You"

1.4 Available Layouts

Layout	Class	Best For
Two Column	two-col > col + col	Two parallel topics with sub-lists
Feature Cards	feature-grid > feature-card tilt-card	3–4 key concepts (clickable with modal)
Stats Grid	stats-grid > stat-card tilt-card	Numeric statistics with counter animation
Timeline	timeline > timeline-item	Sequential phases / steps
Bullet List	ul > li	Simple list of points
Table	table.stage-table	Structured data
Q&A Examples	.qa-example blocks	Show input/output samples side-by-side
Image	<img>	Visual content

1.5 Available Animations

Animation	Class	Use For
Fade Up	reveal	Default for most elements
Fade Left	reveal-left	Left-column content in two-col
Scale In	reveal-scale	Cards, images
Blur In	reveal-blur	Title text, logos, big headings
Draw Line	anim-draw	Decorative lines

Stagger delays: start at 0.05s, increment by 0.08s–0.10s per element.

1.6 Available Decorations

Decoration	Class / Element	Applies To
Gradient Orbs	.orb.orb-1, .orb-2, .orb-3	Title & End slides
Gold Bottom Line	.gold-line-bottom	Title & End slides
Purple Left Bar	.purple-bar	Content slides
Gold Top Rule	.gold-rule	Some content slides (alternating)
Geometric Corner	.geo-corner	Some content slides (accent)

1.7 Output Format: Slide Plan Markdown

Write the plan to {basename}-slides-plan.md in the same directory as the source. Use this exact format:

# Slide Plan: {Presentation Title}

Source: `{source-filename.md}`
Template: `cuhk-template.html`
Total slides: {N}
Sections: {list of section names}

---

## Slide 0 — Title

- **Type**: `title-slide noise`
- **Background**: Dark (#2A1533)
- **Decorations**: orb-1, orb-2, orb-3, gold-line-bottom
- **Animations**:
  - CUHK logo: `reveal-blur` delay 0s
  - University name: `reveal-blur` delay 0.1s
  - Title divider: `anim-draw`
  - H1 title: `reveal-blur` delay 0.25s
  - Subtitle: `reveal-blur` delay 0.4s
  - Author info: `reveal` delay 0.55s
- **Content**:
  - Title: "..."
  - Subtitle: "..."
  - Author: "..."

---

## Slide 1 — Outline

- **Type**: `content-slide`
- **Background**: White
- **Decorations**: purple-bar, gold-rule, geo-corner
- **Layout**: Agenda list (clickable, links to section slides)
- **Animations**: Each item `reveal` with staggered delay (0.12s, 0.2s, 0.28s, ...)
- **Content**:
  1. "Section Name 1" → goto slide N
  2. "Section Name 2" → goto slide N
  ...

---

## Slide 2 — Section: {Name}

- **Type**: `section-slide noise`
- **Background**: Purple gradient
- **Section Number**: 01
- **Animations**:
  - Gold dot: `reveal` delay 0.05s
  - H2: `reveal` delay 0.15s
  - Description: `reveal` delay 0.3s
- **Content**:
  - Title: "..."
  - Description: "..."

---

## Slide 3 — {Slide Title}

- **Type**: `content-slide warm`
- **Background**: Cream
- **Decorations**: purple-bar
- **Layout**: two-col
- **Animations**:
  - H2: `reveal` delay 0.05s
  - Left col: `reveal-left` delay 0.15s
  - Right col: `reveal-left` delay 0.3s
- **Content**:
  - Left column title: "..."
  - Left column items: [...]
  - Right column title: "..."
  - Right column items: [...]

---

## Slide N — {Slide Title}

- **Type**: `content-slide`
- **Background**: White
- **Decorations**: purple-bar, gold-rule, geo-corner
- **Layout**: feature-grid (3 cards, with modals)
- **Animations**:
  - H2: `reveal` delay 0.05s
  - Card 1: `reveal-scale` delay 0.15s
  - Card 2: `reveal-scale` delay 0.25s
  - Card 3: `reveal-scale` delay 0.35s
- **Content**:
  - Card 1: num="01", title="...", summary="...", details="..."
  - Card 2: num="02", title="...", summary="...", details="..."
  - Card 3: num="03", title="...", summary="...", details="..."

---

## Slide N — {Slide Title}

- **Type**: `content-slide`
- **Background**: White
- **Decorations**: purple-bar, gold-rule
- **Layout**: stats-grid (3 stats, counter animation)
- **Animations**:
  - H2: `reveal` delay 0.05s
  - Stats grid: `reveal` delay 0.15s
- **Content**:
  - Stat 1: target=42, suffix="%", label="..."
  - Stat 2: target=128, suffix="K", label="..."
  - Stat 3: target=5, suffix="", label="..."

---

## Slide N — Quote

- **Type**: `quote-slide noise`
- **Background**: Cream
- **Animations**:
  - Blockquote: `reveal-blur` delay 0.15s
  - Attribution: `reveal` delay 0.4s
- **Content**:
  - Quote: "..."
  - Attribution: "..."

---

## Slide N — Comparison: {Title}

- **Type**: split (no slide class, uses `split-panel`)
- **Background**: Left=cream, Right=dark
- **Layout**: split-panel with VS badge
- **Animations**:
  - Left tag: `reveal-left` delay 0.1s
  - Left h3: `reveal-left` delay 0.2s
  - Left items: `reveal-left` staggered from 0.3s
  - Right tag: `reveal` delay 0.1s
  - Right h3: `reveal` delay 0.2s
  - Right items: `reveal` staggered from 0.3s
  - VS badge: `reveal-scale` delay 0.5s
- **Content**:
  - Left tag: "..."
  - Left title: "..."
  - Left items: [...]
  - Right tag: "..."
  - Right title: "..."
  - Right items: [...]

---

## Slide N — {Slide Title}

- **Type**: `content-slide warm`
- **Background**: Cream
- **Decorations**: purple-bar
- **Layout**: timeline (4 items)
- **Animations**:
  - H2: `reveal` delay 0.05s
  - Each item: `reveal` staggered (gold line draws via CSS)
- **Content**:
  - Item 1: label="...", desc="..."
  - Item 2: label="...", desc="..."
  - Item 3: label="...", desc="..."
  - Item 4: label="...", desc="..."

---

## Slide N — {Slide Title}

- **Type**: `content-slide`
- **Background**: White
- **Decorations**: purple-bar, gold-rule
- **Layout**: stage-table
- **Animations**:
  - H2: `reveal` delay 0.05s
  - Table: `reveal` delay 0.15s
- **Content**:
  - Headers: [col1, col2, col3, col4]
  - Rows: [[...], [...], ...]

---

## Slide {last} — End

- **Type**: `end-slide noise`
- **Background**: Dark (#2A1533)
- **Decorations**: orb-1, orb-2, gold-line-bottom
- **Animations**:
  - CUHK logo: `reveal-blur` delay 0.05s
  - Divider: `reveal` delay 0.1s
  - "Thank You": `reveal-blur` delay 0.2s
  - Subtitle: `reveal` delay 0.35s
  - Contact: `reveal` delay 0.5s
- **Content**:
  - Contact: "..."

---

## Metadata

- **SECTION_STARTS**: [2, 5, 9] (0-indexed slide indices of section-slides)
- **Footer label**: "Your Presentation"

1.8 Design Principles for Planning

• One idea per slide. Never cram multiple H3-level topics into one slide.
• Alternate warm / default backgrounds for adjacent content slides to create visual rhythm.
• Limit text per slide. If a section has dense content, split into multiple slides.
• Use feature-grid for 3–4 parallel concepts, stats-grid for numbers, two-col for comparisons.
• Every section starts with a section-slide (purple header) before its content slides.
• Use quote-slide for impactful one-liners or key insights.
• Add geo-corner decoration to slides that also have gold-rule (not every slide).

---

Step 2: Generate HTML from the Slide Plan

2.1 Read the Plan

Read the slide plan markdown (either just generated in Step 1, or provided by the user).

2.2 Read the Template

Read assets/cuhk-template.html for the exact CSS and JS to copy.

2.3 Generate the HTML

The output HTML must be self-contained (single file, inline CSS + JS).

Structure

<!DOCTYPE html>
<html lang="en">
<head>
    <!-- Google Fonts: Crimson Pro, Noto Serif SC, Outfit -->
    <style>
        /* Copy ALL CSS from template exactly */
    </style>
</head>
<body>
    <!-- Fixed UI (copy from template):
         card-modal-overlay, custom cursor, progress-bar, nav-dots,
         section-breadcrumb, presenter-timer, shortcuts-overlay, overview-overlay -->

    <!-- SLIDES: each is a <section class="slide ..."> -->

    <script>
        /* Copy ALL JS from template exactly */
        /* Update SECTION_STARTS array to match the Metadata in the plan */
    </script>
</body>
</html>

Per-Slide HTML Requirements

Every slide must have:

• data-slide="N" (0-indexed, matching plan)
• data-section="NN / SectionName" (empty for title / outline / end / quote)
• data-title="Short Title" (used for nav-dot tooltips)
• <div class="slide-footer"><span>{footer-label}</span><span>N+1</span></div> (use empty number for title and end slides)

Translating Plan to HTML

For each slide in the plan:

1. Create <section class="slide {Type}"> with appropriate data attributes.
2. Add Decorations as listed (orbs, purple-bar, gold-rule, geo-corner).
3. Create <div class="slide-content"> with the specified Layout.
4. Apply Animation classes and --delay values exactly as specified.
5. Fill in Content from the plan.

Feature Cards with Modals

For feature-card elements, add modal data attributes:

<div class="feature-card tilt-card reveal-scale" style="--delay:0.15s"
     data-modal-num="01" data-modal-title="Card Title"
     data-modal-summary="Summary text"
     data-modal-details="&lt;ul&gt;&lt;li&gt;Detail 1&lt;/li&gt;&lt;li&gt;Detail 2&lt;/li&gt;&lt;/ul&gt;">
    <div class="card-num">01</div>
    <h3>Card Title</h3>
    <p>Brief description</p>
    <div class="card-hint">Click to expand</div>
</div>

Counter Animation

For stat numbers, use:

<span class="counter" data-target="42" data-suffix="%">0%</span>

SECTION_STARTS

In the JS, set SECTION_STARTS to the array from the plan's Metadata section. This controls the visual gaps in the right-side nav dots.

2.4 Image Handling

If the plan references images, include them as <img> tags with the same relative path as the source markdown uses. Always reference cuhk_logo.png on the title and end slides; the user is expected to drop their own logo in next to the HTML or replace this filename.

2.5 Output

Write the HTML file to the same directory as the source, using the base name plus -slides.html (e.g., talk.md → talk-slides.html).

---

Summary of Outputs

Step	Input	Output
Step 1	{name}.md (source)	{name}-slides-plan.md (slide-by-slide plan)
Step 2	{name}-slides-plan.md + assets/cuhk-template.html	{name}-slides.html (final presentation)

---

Built-in Keyboard Shortcuts

The generated HTML includes these built-in shortcuts (no extra wiring needed — they come from the template's JS):

Key	Action
→ / Space / PageDown	Next slide
← / PageUp	Previous slide
↓	Next slide
↑	Previous slide
Home	Jump to first slide
End	Jump to last slide
O	Toggle slide overview grid
T	Toggle presenter timer (bottom-center)
?	Show keyboard-shortcut help overlay
Esc	Close any open overlay or modal

Mention these in the README of any presentation you ship so the audience and presenter know they exist.