Markdown to Page

SKILL.md

---
name: md-to-page
description: Convert Markdown files into beautiful, scrollable wide-screen HTML pages with dark/light theme toggle, scroll animations, and rich directive components. Use when the user wants to turn a .md file into a presentable HTML page, create a long-form web article from markdown, generate a scrollable one-pager, or make a shareable HTML document from notes/outlines. Triggers on: markdown to HTML, generate page from md, scrollable page, wide-screen page, one-pager, web article from markdown.
---

# 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

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:

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