Markdown to Page

# md-to-page

Convert Markdown into polished, scrollable wide-screen HTML pages with built-in dark/light theme toggle.

Quick Start

```bash python3 SKILL_DIR/scripts/md_to_page.py INPUT.md OUTPUT.html [options] ```

Options

| Flag | Description | Default | |------|-------------|---------| | `--embed-images` | Compress local images (Pillow) and embed as base64 data URIs | off | | `--title TEXT` | Override HTML page title | First H1 | | `--footer TEXT` | Custom footer text | "Generated by md-to-page" |

Features

Standard Markdown - **H1** → full-screen hero title (first paragraph under H1 = subtitle) - **H2** → numbered section dividers (01, 02, ...) - **H3/H4** → section/sub-section headings - **Bold**, *italic*, `inline code`, [links](url), images - Unordered and ordered lists - Fenced code blocks with syntax display - Blockquote callouts (`>`, `> 💡`, `> ⚠️`) - Markdown tables → styled responsive tables - Horizontal rules → ignored (sections provide visual separation)

File Trees

````markdown ```tree workspace/ ├── SOUL.md # System prompt ├── memory/ │ └── 2026-03-01.md └── skills/ ``` ````

::: Directive Blocks

Extended syntax using fenced `:::` blocks for rich components.

#### Card

```markdown ::: card Content with bold and `code` ::: ```

#### Card Grid

```markdown ::: card-grid ::: card {icon=💬 title="Chat"} Natural language interface ::: ::: card {icon=📄 title="Docs"} Auto-generated documentation ::: ::: ```

#### Compare (Good vs Bad)

```markdown ::: compare ::: side bad {label="❌ Before"} Manual copy-paste workflow ::: ::: side good {label="✅ After"} Automated pipeline ::: ::: ```

#### Flow

```markdown ::: flow Write docs → AI helps write → *Store in Confluence* → AI reads → Summary ::: ```

• Normal text = regular step
• `*text*` = highlighted step (accent border + glow)
• `~text~` = dead/deprecated step (strikethrough + faded)
• Arrows `→` `←` rendered as connector arrows

Deprecated flow with opacity:

```markdown ::: flow dead-suffix Store in Confluence ← No longer needed ::: ```

#### Quote Block

```markdown ::: quote The best interface is no interface. — Golden Krishna ::: ```

#### Layers

```markdown ::: layers Personal | Your preferences, projects, habits Team | Onboarding, SOP, tech decisions Organization | Company policies, cross-BU knowledge ::: ```

Format: `Tag | Description` per line. Each layer gets a distinct color (up to 4 built-in colors).

#### Cycle

```markdown ::: cycle negative Wrote docs → Nobody updates → Outdated → Nobody reads → ↻ :::

::: cycle positive Write to memory → AI answers → People use → AI updates → ↻ ::: ```

Polarity: `negative` (pink) or `positive` (cyan).

#### Command List

```markdown ::: cmd-list /status — Check agent status /model — Switch model /new — Reset context ::: ```

Format: `command — description` per line, rendered in monospace with accent-colored keys.

Image Embedding

1. With `--embed-images`, local image paths in `!alt` are:
2. Loaded from disk (relative to the input .md file)
3. Compressed via Pillow (max 1200px wide, JPEG quality 75)
4. Embedded as `data:image/jpeg;base64,...` URIs
5. If Pillow is not installed, raw file bytes are base64-encoded without compression

URLs (`http://`, `https://`) are left unchanged.

Theme Toggle

Every generated page includes a 🌙/☀️ toggle button (top-right corner) that switches between dark and light themes. Theme preference is saved to `localStorage`.

• Dark (default): Deep navy background, gradient accents, purple/cyan colors
• Light: White background, subtle gray cards, clean typography

Markdown Tables

Standard pipe tables are auto-detected and rendered as styled tables:

```markdown | Feature | Status | |---------|--------| | Dark mode | ✅ | | Light mode | ✅ | ```

When NOT to Use

• For slide decks / presentations → use `presentation-generator` or `slides-cog`
• For Obsidian notes → use `obsidian-markdown`