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.
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 |
✅ |
Syntax highlighting, monospace font |
| 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 |
| Math (KaTeX) |
⚠️ |
Requires --katex flag |
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
# 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 8, 2400px width for crisp output. 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:
- Page breaks before H1 headings
- No background colors (ink-friendly)
- Link URLs shown after text
- Code blocks with borders instead of background
- Proper margins for binding
Batch Processing
# 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 (v1.0.0)
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 |
| Math equations (KaTeX/MathJax) render correctly |
Accept |
Spot-check complex equations |
| Math equations show raw LaTeX source |
Reject |
Verify KaTeX CSS/JS included in template |
| 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 — Sister converter for Word document output
- md-scaffold — Generate converter-ready Markdown templates
- markdown-mermaid — Diagram authoring for embedded Mermaid
- lint-clean-markdown — Pre-validate markdown before conversion
- nav-inject — Add navigation tables for multi-file suites
Skill version: 2.0.0 | Last updated: 2026-04-14 | Category: document-conversion
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
1---2name: md-to-html3description: Convert Markdown to standalone HTML pages with embedded CSS, images, and Mermaid diagrams4---5
6# Md To Html
7
8> Write in Markdown, share as a polished web page — zero dependencies for viewers
9
10Convert 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.
11
12---
13
14## When to Use
15
16- Sharing formatted documents without requiring Word or PDF viewers
17- Creating self-contained HTML pages for offline distribution
18- Generating printable web pages from Markdown sources
19- Quick previews of documentation with professional styling
20- Email attachments that open in any browser
21- Static site generation from Markdown sources
22
23---
24
25## Supported Formatting
26
27| Format | Status | Notes |
28|--------|--------|-------|
29| **Headings** | ✅ | H1-H6 with styled colors |
30| **Bold/Italic** | ✅ | Standard emphasis |
31| **Links** | ✅ | Styled with underline on hover |
32| **Images** | ✅ | Base64 embedded or linked |
33| **Code blocks** | ✅ | Syntax highlighting, monospace font |
34| **Inline code** | ✅ | Background highlight |
35| **Tables** | ✅ | Striped rows, header styling |
36| **Blockquotes** | ✅ | Left border, italic style |
37| **Lists** | ✅ | Ordered, unordered, nested |
38| **Task lists** | ✅ | Checkbox rendering |
39| **Mermaid diagrams** | ✅ | PNG or table fallback |
40| **SVG** | ✅ | Inline or base64 embedded |
41| **Horizontal rules** | ✅ | Styled dividers |
42| **Footnotes** | ✅ | Via pandoc |
43| **Math (KaTeX)** | ⚠️ | Requires --katex flag |
44
45---
46
47## Key Features
48
49| Feature | Details |
50|---------|---------|
51| Style presets | professional, academic, minimal, dark |
52| Self-contained | All CSS embedded in `<style>` block, no external deps |
53| Image embedding | Local images converted to base64 data URIs |
54| Mermaid support | PNG rendering or table fallback for diagrams |
55| Print-ready | CSS `@media print` rules included |
56| TOC generation | Optional table of contents via `--toc` |
57| Frontmatter | Extracted for title, stripped from output |
58
59## Usage
60
61```bash
62# Basic conversion (professional style)
63node .github/skills/md-to-html/scripts/md-to-html.cjs report.md
64
65# Academic style with TOC
66node .github/skills/md-to-html/scripts/md-to-html.cjs thesis.md --style academic --toc
67
68# Dark mode output
69node .github/skills/md-to-html/scripts/md-to-html.cjs docs.md --style dark
70
71# Mermaid diagrams rendered as PNG (high quality)
72node .github/skills/md-to-html/scripts/md-to-html.cjs architecture.md --mermaid-png
73
74# Custom output path
75node .github/skills/md-to-html/scripts/md-to-html.cjs README.md output/readme.html
76
77# Dry run (validate without generating)
78node .github/skills/md-to-html/scripts/md-to-html.cjs report.md --dry-run
79
80# Debug mode (save preprocessed markdown)
81node .github/skills/md-to-html/scripts/md-to-html.cjs report.md --debug
82```
83
84---
85
86## Options Reference
87
88| Option | Default | Description |
89|--------|---------|-------------|
90| `--style PRESET` | professional | Style preset: professional, academic, minimal, dark |
91| `--toc` | off | Generate table of contents from headings |
92| `--embed-images` | true | Convert local images to base64 data URIs |
93| `--no-embed-images` | - | Keep image paths as-is (external references) |
94| `--strip-frontmatter` | true | Remove YAML frontmatter from output |
95| `--mermaid-png` | off | Render Mermaid as PNG (requires mmdc) |
96| `--mermaid-fallback` | default | Convert Mermaid to table representation |
97| `--debug` | off | Save preprocessed markdown as _debug_combined.md |
98| `--dry-run` | off | Validate only, no HTML output |
99
100---
101
102## Style Presets
103
104| Preset | Font | Max Width | Colors | Best For |
105|--------|------|-----------|--------|----------|
106| **professional** | Segoe UI | 900px | Blue headings, white bg | Business docs, reports |
107| **academic** | Palatino Linotype | 750px | Dark headings, cream bg | Papers, theses |
108| **minimal** | Inter | 800px | Black/gray, white bg | Clean, modern pages |
109| **dark** | Segoe UI | 900px | Light text, dark bg | Dark mode preference |
110
111---
112
113## Mermaid Diagram Support
114
115| Diagram Type | PNG Mode | Fallback Mode |
116|--------------|----------|---------------|
117| Flowchart | ✅ Full render | ✅ Table |
118| Sequence | ✅ Full render | ✅ Table |
119| Class | ✅ Full render | ✅ Table |
120| State | ✅ Full render | ✅ Table |
121| ER | ✅ Full render | ✅ Table |
122| Gantt | ✅ Full render | ⚠️ Limited |
123| Pie | ✅ Full render | ✅ Table |
124| Journey | ✅ Full render | ⚠️ Limited |
125
126**PNG Mode** (`--mermaid-png`): Requires mermaid-cli (mmdc). Renders at scale 8, 2400px width for crisp output. Diagrams are embedded as base64 PNGs.
127
128**Fallback Mode** (default): No external dependencies. Converts diagram syntax to an ASCII table representation suitable for text-only viewing.
129
130---
131
132## Print Styling
133
134HTML output includes `@media print` CSS rules:
135
136- Page breaks before H1 headings
137- No background colors (ink-friendly)
138- Link URLs shown after text
139- Code blocks with borders instead of background
140- Proper margins for binding
141
142---
143
144## Batch Processing
145
146```bash
147# Convert all markdown files in a directory
148for file in docs/*.md; do
149 node .github/skills/md-to-html/scripts/md-to-html.cjs "$file" --style professional
150done
151
152# PowerShell equivalent
153Get-ChildItem docs/*.md | ForEach-Object {
154 node .github/skills/md-to-html/scripts/md-to-html.cjs $_.FullName --style professional
155}
156```
157
158---
159
160## Troubleshooting
161
162| Problem | Cause | Solution |
163|---------|-------|----------|
164| "pandoc not found" | pandoc not installed | `winget install pandoc` |
165| Mermaid not rendering | mmdc not installed | `npm install -g @mermaid-js/mermaid-cli` or use fallback |
166| Images missing | Relative paths broken | Use `--embed-images` (default) |
167| Output too wide on print | Style preset issue | Use academic style for print |
168| Special characters garbled | Encoding issue | Ensure source is UTF-8 |
169
170---
171
172## Requirements
173
174- Node.js 24+
175- pandoc (`winget install pandoc`)
176- mermaid-cli (optional, only for `--mermaid-png`)
177
178---
179
180## Muscle Script
181
182`.github/skills/md-to-html/scripts/md-to-html.cjs` (v1.0.0)
183
184---
185
186## Conversion Acceptance Decision Table
187
188| Condition | Verdict | Action |
189|-----------|---------|--------|
190| All headings, lists, tables, code blocks render correctly | Accept | Ship as-is |
191| Mermaid diagrams rendered as PNG/SVG with correct layout | Accept | Verify diagram labels readable |
192| Mermaid diagrams missing or show raw syntax | Reject | Check mermaid-cli installed; re-run with `--mermaid-png` |
193| Math equations (KaTeX/MathJax) render correctly | Accept | Spot-check complex equations |
194| Math equations show raw LaTeX source | Reject | Verify KaTeX CSS/JS included in template |
195| Embedded images display at correct size | Accept | Confirm no broken `<img>` tags |
196| Images missing or show broken placeholders | Reject | Check paths are relative and files exist |
197| CSS custom properties resolve (colors, fonts) | Accept | Visual spot-check against brand |
198| Inline styles lost or overridden by browser defaults | Warning | Add `!important` or inline fallbacks |
199| Output file size >5MB for a simple document | Warning | Check for unoptimized base64 images |
200| HTML validates (no unclosed tags, no script injection) | Accept | Required for security |
201| HTML contains `<script>` from untrusted source | Reject | Sanitize; only allow known libraries |
202
203---
204
205## Related Skills
206
207- **md-to-word** — Sister converter for Word document output
208- **md-scaffold** — Generate converter-ready Markdown templates
209- **markdown-mermaid** — Diagram authoring for embedded Mermaid
210- **lint-clean-markdown** — Pre-validate markdown before conversion
211- **nav-inject** — Add navigation tables for multi-file suites
212
213---
214
215*Skill version: 2.0.0 | Last updated: 2026-04-14 | Category: document-conversion*
216
217## Falsifiability
218
219- This skill is wrong if generated HTML fails W3C validation on structural elements the skill explicitly handles
220- The conversion flags are stale if Pandoc changes default HTML5 output behavior in a major version
221- Not earning tokens if the output loses semantic structure (headings, lists, code blocks) that raw Pandoc preserves without the documented options
fabioc-aloha