---
name: "md-to-html"
description: "Convert Markdown to standalone HTML pages with embedded CSS, images, and Mermaid diagrams. Use when the user asks to convert to HTML, make a webpage, or export markdown as an .html file."
lastReviewed: 2026-07-28
---



# Md To Html

> Write in Markdown, share as a polished web page — zero dependencies for viewers

Convert Markdown documents into self-contained HTML files with embedded CSS, base64 images, and Mermaid diagram rendering. Ready for quick-share distribution, offline viewing, print, or email attachment.

> [!WARNING]
> This converter rejects executable raw HTML such as `<script>`, event-handler
> attributes, and `javascript:` URLs. Sanitize externally supplied Markdown
> before conversion; do not weaken this boundary to make an untrusted document
> render.

---

## When to Use

- Sharing formatted documents without requiring Word or PDF viewers
- Creating self-contained HTML pages for offline distribution
- Generating printable web pages from Markdown sources
- Quick previews of documentation with professional styling
- Email attachments that open in any browser
- Static site generation from Markdown sources

---



## Supported Formatting

| Format | Status | Notes |
|--------|--------|-------|
| **Headings** | ✅ | H1-H6 with styled colors |
| **Bold/Italic** | ✅ | Standard emphasis |
| **Links** | ✅ | Styled with underline on hover |
| **Images** | ✅ | Base64 embedded or linked |
| **Code blocks** | ✅ | Monospace styling |
| **Inline code** | ✅ | Background highlight |
| **Tables** | ✅ | Striped rows, header styling |
| **Blockquotes** | ✅ | Left border, italic style |
| **Lists** | ✅ | Ordered, unordered, nested |
| **Task lists** | ✅ | Checkbox rendering |
| **Mermaid diagrams** | ✅ | PNG or table fallback |
| **SVG** | ✅ | Inline or base64 embedded |
| **Horizontal rules** | ✅ | Styled dividers |
| **Footnotes** | ✅ | Via pandoc |

---

## Key Features

| Feature | Details |
|---------|---------|
| Style presets | professional, academic, minimal, dark |
| Self-contained | All CSS embedded in `<style>` block, no external deps |
| Image embedding | Local images converted to base64 data URIs |
| Mermaid support | PNG rendering or table fallback for diagrams |
| Print-ready | CSS `@media print` rules included |
| TOC generation | Optional table of contents via `--toc` |
| Frontmatter | Extracted for title, stripped from output |

## Usage

```bash
# Basic conversion (professional style)
node .github/skills/md-to-html/scripts/md-to-html.cjs report.md

# Academic style with TOC
node .github/skills/md-to-html/scripts/md-to-html.cjs thesis.md --style academic --toc

# Dark mode output
node .github/skills/md-to-html/scripts/md-to-html.cjs docs.md --style dark

# Mermaid diagrams rendered as PNG (high quality)
node .github/skills/md-to-html/scripts/md-to-html.cjs architecture.md --mermaid-png

# Custom output path
node .github/skills/md-to-html/scripts/md-to-html.cjs README.md output/readme.html

# Dry run (validate without generating)
node .github/skills/md-to-html/scripts/md-to-html.cjs report.md --dry-run

# Debug mode (save preprocessed markdown)
node .github/skills/md-to-html/scripts/md-to-html.cjs report.md --debug
```

---



## Options Reference

| Option | Default | Description |
|--------|---------|-------------|
| `--style PRESET` | professional | Style preset: professional, academic, minimal, dark |
| `--toc` | off | Generate table of contents from headings |
| `--embed-images` | true | Convert local images to base64 data URIs |
| `--no-embed-images` | - | Keep image paths as-is (external references) |
| `--strip-frontmatter` | true | Remove YAML frontmatter from output |
| `--mermaid-png` | off | Render Mermaid as PNG (requires mmdc) |
| `--mermaid-fallback` | default | Convert Mermaid to table representation |
| `--debug` | off | Save preprocessed markdown as _debug_combined.md |
| `--dry-run` | off | Validate only, no HTML output |

---

## Style Presets

| Preset | Font | Max Width | Colors | Best For |
|--------|------|-----------|--------|----------|
| **professional** | Segoe UI | 900px | Blue headings, white bg | Business docs, reports |
| **academic** | Palatino Linotype | 750px | Dark headings, cream bg | Papers, theses |
| **minimal** | Inter | 800px | Black/gray, white bg | Clean, modern pages |
| **dark** | Segoe UI | 900px | Light text, dark bg | Dark mode preference |

---



## Mermaid Diagram Support

| Diagram Type | PNG Mode | Fallback Mode |
|--------------|----------|---------------|
| Flowchart | ✅ Full render | ✅ Table |
| Sequence | ✅ Full render | ✅ Table |
| Class | ✅ Full render | ✅ Table |
| State | ✅ Full render | ✅ Table |
| ER | ✅ Full render | ✅ Table |
| Gantt | ✅ Full render | ⚠️ Limited |
| Pie | ✅ Full render | ✅ Table |
| Journey | ✅ Full render | ⚠️ Limited |

**PNG Mode** (`--mermaid-png`): Requires mermaid-cli (`mmdc`). Renders at scale 3 and 1200px width. Diagrams are embedded as base64 PNGs.

**Fallback Mode** (default): No external dependencies. Converts diagram syntax to an ASCII table representation suitable for text-only viewing.

---

## Print Styling

HTML output includes `@media print` CSS rules:

- Full-width body with page padding removed
- Text-colored links without underlines
- Code blocks with borders instead of background

---



## Batch Processing

```bash
# Convert all markdown files in a directory
for file in docs/*.md; do
  node .github/skills/md-to-html/scripts/md-to-html.cjs "$file" --style professional
done

# PowerShell equivalent
Get-ChildItem docs/*.md | ForEach-Object {
  node .github/skills/md-to-html/scripts/md-to-html.cjs $_.FullName --style professional
}
```

---

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| "pandoc not found" | pandoc not installed | `winget install pandoc` |
| Mermaid not rendering | mmdc not installed | `npm install -g @mermaid-js/mermaid-cli` or use fallback |
| Images missing | Relative paths broken | Use `--embed-images` (default) |
| Output too wide on print | Style preset issue | Use academic style for print |
| Special characters garbled | Encoding issue | Ensure source is UTF-8 |

---



## Requirements

- Node.js 24+
- pandoc (`winget install pandoc`)
- mermaid-cli (optional, only for `--mermaid-png`)

---

## Muscle Script

`.github/skills/md-to-html/scripts/md-to-html.cjs`

---



## Conversion Acceptance Decision Table

| Condition | Verdict | Action |
|-----------|---------|--------|
| All headings, lists, tables, code blocks render correctly | Accept | Ship as-is |
| Mermaid diagrams rendered as PNG/SVG with correct layout | Accept | Verify diagram labels readable |
| Mermaid diagrams missing or show raw syntax | Reject | Check mermaid-cli installed; re-run with `--mermaid-png` |
| Embedded images display at correct size | Accept | Confirm no broken `<img>` tags |
| Images missing or show broken placeholders | Reject | Check paths are relative and files exist |
| CSS custom properties resolve (colors, fonts) | Accept | Visual spot-check against brand |
| Inline styles lost or overridden by browser defaults | Warning | Add `!important` or inline fallbacks |
| Output file size >5MB for a simple document | Warning | Check for unoptimized base64 images |
| HTML validates (no unclosed tags, no script injection) | Accept | Required for security |
| HTML contains `<script>` from untrusted source | Reject | Sanitize; only allow known libraries |

---

## Related Skills

- [md-to-word](../md-to-word/SKILL.md) - sister converter for Word output
- Mermaid authoring - use a Mermaid-capable skill; when Core is installed, its `markdown-mermaid` skill provides diagram guidance
- Markdown linting - validate the source with the project's linter or Core's `lint-clean-markdown` skill

---



## Falsifiability

- This skill is wrong if generated HTML fails W3C validation on structural elements the skill explicitly handles
- The conversion flags are stale if Pandoc changes default HTML5 output behavior in a major version
- Not earning tokens if the output loses semantic structure (headings, lists, code blocks) that raw Pandoc preserves without the documented options