Markdown To Html

Markdown to HTML Converter

Why this skill exists

Raw markdown-to-HTML conversion gives unstyled output. Users almost always want a readable, styled page — not just wrapped `` tags. This skill produces beautiful, self-contained HTML with sensible defaults.

When to use

• User has a .md file and wants a web-ready HTML page
• User wants to convert README, docs, or blog post to a shareable HTML file
• User wants a styled, printable document from markdown

Step-by-step procedure

Step 1 — Read the markdown file

from pathlib import Path

md_path = "/mnt/user-data/uploads/document.md"
content = Path(md_path).read_text(encoding="utf-8")
print(f"Read {len(content)} chars, {content.count(chr(10))} lines")

Step 2 — Convert with python-markdown

pip install markdown pymdown-extensions --break-system-packages -q

import markdown

md = markdown.Markdown(extensions=[
    "tables",           # GFM-style tables
    "fenced_code",      # ```code blocks```
    "codehilite",       # syntax highlighting
    "toc",              # [TOC] table of contents
    "nl2br",            # newlines → 
    "pymdownx.tasklist", # - [x] checkboxes
    "attr_list",        # {.class} attributes
])

html_body = md.convert(content)
toc = md.toc  # if [TOC] was in the document

Step 3 — Wrap in a styled HTML page

def build_html_page(body: str, title: str = "Document", toc: str = "") -> str:
    return f"""

{title}

  *, *::before, *::after {{ box-sizing: border-box; }}
  body {{
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
    font-size: 16px;
    line-height: 1.7;
    color: #1a1a1a;
    max-width: 780px;
    margin: 0 auto;
    padding: 2rem 1.5rem;
    background: #fff;
  }}
  h1, h2, h3, h4, h5, h6 {{
    font-weight: 600;
    line-height: 1.3;
    margin: 2rem 0 0.75rem;
    color: #111;
  }}
  h1 {{ font-size: 2rem; border-bottom: 2px solid #e5e5e5; padding-bottom: 0.5rem; }}
  h2 {{ font-size: 1.5rem; border-bottom: 1px solid #e5e5e5; padding-bottom: 0.3rem; }}
  a {{ color: #0066cc; text-decoration: none; }}
  a:hover {{ text-decoration: underline; }}
  code {{
    font-family: "SF Mono", Consolas, monospace;
    font-size: 0.875em;
    background: #f5f5f5;
    padding: 0.2em 0.4em;
    border-radius: 4px;
  }}
  pre {{
    background: #1e1e1e;
    color: #d4d4d4;
    padding: 1.25rem;
    border-radius: 8px;
    overflow-x: auto;
    font-size: 0.875rem;
    line-height: 1.5;
  }}
  pre code {{ background: none; padding: 0; color: inherit; font-size: inherit; }}
  blockquote {{
    border-left: 4px solid #ddd;
    margin: 0;
    padding: 0.5rem 1.25rem;
    color: #555;
    background: #fafafa;
  }}
  table {{
    border-collapse: collapse;
    width: 100%;
    margin: 1.5rem 0;
    font-size: 0.9rem;
  }}
  th, td {{ border: 1px solid #ddd; padding: 0.6rem 1rem; text-align: left; }}
  th {{ background: #f5f5f5; font-weight: 600; }}
  tr:nth-child(even) {{ background: #fafafa; }}
  img {{ max-width: 100%; height: auto; border-radius: 6px; }}
  hr {{ border: none; border-top: 1px solid #e5e5e5; margin: 2rem 0; }}
  .task-list-item {{ list-style: none; }}
  .task-list-item input {{ margin-right: 0.5em; }}
  .toc {{ background: #f8f8f8; border: 1px solid #e5e5e5; border-radius: 8px; padding: 1rem 1.5rem; margin-bottom: 2rem; }}
  .toc ul {{ margin: 0; }}
  @media print {{
    body {{ max-width: 100%; padding: 1rem; }}
    pre {{ white-space: pre-wrap; }}
  }}

{"" + toc + "" if toc else ""}
{body}

"""

Step 4 — Detect title and save

import re

# Extract title from first H1
title_match = re.search(r'^#\s+(.+)', content, re.MULTILINE)
title = title_match.group(1) if title_match else "Document"

html = build_html_page(html_body, title=title, toc=toc)

output_path = "/mnt/user-data/outputs/document.html"
Path(output_path).write_text(html, encoding="utf-8")
print(f"✅ HTML saved: {output_path}")
print(f"   Size: {len(html) / 1024:.1f} KB")

Alternative — pandoc (for complex documents)

# Pandoc produces excellent output with full LaTeX math support
pip install pandoc --break-system-packages -q  # or: apt-get install pandoc

pandoc /mnt/user-data/uploads/document.md \
  --standalone \
  --self-contained \
  --highlight-style=github \
  -o /mnt/user-data/outputs/document.html

echo "Converted with pandoc"

Edge cases

| Situation | Fix | |-----------|-----| | Relative image paths | Rewrite to absolute or embed as base64 | | Math equations (LaTeX) | Add MathJax CDN script to ` | | Multiple files | Convert each, optionally merge into one page | | Dark mode request | Add @media (prefers-color-scheme: dark) CSS block | | Print-ready PDF from HTML | Use weasyprint` or suggest browser print-to-PDF | | Custom CSS provided by user | Append it after the default styles |

Output format

Report:

• Input file and character count
• Output HTML path and file size
• Whether a TOC was generated
• Any images or assets that weren't resolved

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: prasad-nimbalkar
• Source: prasad-nimbalkar/claude-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.