Home

mdparser-html Wiki

A lightweight, extensible Markdown → HTML parser with a clean Python API and CLI.

Designed for learning, hackability, and real-world tooling without heavy dependencies.

---

📌 Overview

mdparser-html converts Markdown into clean, modern HTML with optional styling, Tailwind support, and syntax highlighting.

Core goals:

• Simple architecture
• Single public API
• Easy to extend
• Predictable output

---

📦 Installation

pip install mdparser-html

Python ≥ 3.8 required. No runtime dependencies.

---

🚀 Quick Start

CLI

md2html input.md -o output.html

Python API

from mdparser import parse_markdown

html = parse_markdown("# Hello World")
print(html)

---

⚙️ API Reference

parse_markdown()

parse_markdown(
    text: str,
    full_html: bool = True,
    title: str = "Markdown to HTML",
    include_cdn: bool = True
) -> str

Parameters

Name	Type	Description
text	str	Markdown input
full_html	bool	Return full HTML document or body-only
title	str	HTML <title>
include_cdn	bool	Include Prism / Highlight.js / Tailwind

Examples

Full HTML output

html = parse_markdown(md)

Body-only output

body = parse_markdown(md, full_html=False)

Disable CDN

html = parse_markdown(md, include_cdn=False)

---

🧱 Supported Markdown

Headings

# Heading 1
## Heading 2

Styled Headings (Tailwind-ready)

# [text-blue-500 font-bold] Styled Heading

---

Bold / Italic / Inline Code

**bold**
*italic*
`code`

---

Lists

- Item
- Item

1. First
2. Second

---

Images

![Alt text](image.png "Optional title")

---

🧩 Fenced Div Blocks

Custom fenced blocks using ::: with Tailwind classes.

::: hero bg-blue-100 p-4
# Welcome
This is a hero section
:::

Rendered as:

<div class="hero bg-blue-100 p-4">
  <h1>Welcome</h1>
  <p>This is a hero section</p>
</div>

✅ Supports nested fenced divs

---

📊 Tables

Simple, readable table syntax:

:::table
Name | Role | Age
Tarun | Developer | 21
Alex | Tester | 22
:::

Rendered as:

• Semantic <table>
• Styled headers
• Clean borders & spacing

---

🎨 Styling Philosophy

• Headings, tables, fenced divs → styled
• Inline elements remain semantic
• Tailwind classes passed through unchanged
• No forced CSS frameworks

---

🧠 Internal Design

• Single public API: parse_markdown
• Regex + state-machine parsing
• Recursive fenced div handling
• Internal helpers intentionally hidden
• Output-first design (not AST yet)

---

🧪 Testing

• 36+ test cases
• Nested fenced div coverage
• Table edge cases
• CLI + API tests

Run locally:

pytest

---

🗺 Roadmap

• AST-based parser
• Performance optimizations
• Additional output formats (Pug)
• Plugin hooks
• Markdown extensions

---

🤝 Contributing

• Issues welcome
• PRs encouraged
• Architecture discussions preferred before large changes

---

🔗 Links

• 📦 PyPI: https://pypi.org/project/mdparser-html
• 📘 Docs: https://mdparser.tarunnayaka.me
• 🐙 GitHub: https://github.com/Rtarun3606k/mdparser
• 🐛 Issues: https://github.com/Rtarun3606k/mdparser/issues

---

📄 License

MIT License © 2025 Tarun Nayaka R