md-to-page

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

Quick Start

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

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

::: Directive Blocks

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

Card

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

Card Grid

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

Compare (Good vs Bad)

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

Flow

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

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

Quote Block

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

Layers

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

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

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

With --embed-images, local image paths in ![alt](path) are:

1. Loaded from disk (relative to the input .md file)
2. Compressed via Pillow (max 1200px wide, JPEG quality 75)
3. Embedded as data:image/jpeg;base64,... URIs
4. 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:

| 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