A powerful Python CLI tool that converts Markdown files to beautiful, interactive HTML documents with Table of Contents, Dark/Light mode, Mermaid diagram support, and syntax highlighting.
📖 Documentation | 🚀 PyPI | 📝 Changelog
- 🌙 Dark/Light Mode - Toggle between themes with persistence via localStorage
- 📑 Auto Table of Contents - Generated from headings with active section highlighting
- 📊 Mermaid Diagrams - Flowcharts, sequence, class, gantt, pie, state diagrams
- 🎨 Syntax Highlighting - Language-aware code highlighting with Highlight.js
- 🔢 Line Numbers - Code blocks include line numbers
- 📈 Progress Bar - Shows reading progress as you scroll
- 🔝 Back to Top - Floating button for quick navigation
- 📱 Responsive Design - Mobile-friendly with collapsible sidebar
- 🖨️ Print Styles - Clean output when printing
- 🔗 Click-to-Copy - Click any heading to copy its link
- Python 3.9 or higher
- pip or uv (Python package managers)
Install from PyPI:
# HTML converter only
pip install mk2html
# With PDF support
pip install mk2html[pdf]Install as global CLI tool with uv:
uv tool install mk2htmlInstall from source:
git clone https://github.com/km1790/mk2html.git
cd mk2html
pip install -e .Convert a Markdown file to HTML:
mk2html README.mdThis creates README.html in the same directory.
Convert with custom output:
mk2html docs.md -o documentation.htmlConvert to PDF (requires mk2html[pdf]):
mk2pdf README.md -o README.pdfConvert from stdin:
cat input.md | mk2html - -o output.htmlBatch convert all markdown files:
mk2html "*" -o ./html/ # All .md files in current directory
mk2html "*" -o ./html/ -r # Recursively include subdirectories
mk2html "*" -o ./html/ -r --home-link # With home navigation linksusage: mk2html [-h] [-o FILE_OR_DIR] [-r] [-t TITLE] [--theme {light,dark}]
[--no-mermaid] [--no-toc] [--no-breaks] [--no-line-numbers]
[--no-convert-md-links] [--home-link] [--offline]
[--clear-cache] [-q] [-v]
[INPUT]
Convert Markdown to beautiful, interactive HTML with TOC and Mermaid support.
positional arguments:
INPUT Input Markdown file, "-" for stdin, or "*" for batch mode
options:
-h, --help Show this help message and exit
-o FILE_OR_DIR, --output FILE_OR_DIR
Output HTML file or directory (for batch mode with "*")
-r, --recursive Recursively process subdirectories (only with "*" input)
-t TITLE, --title TITLE
Document title (default: filename without extension)
--theme {light,dark} Default theme (default: light)
--no-mermaid Disable Mermaid diagram support
--no-toc Disable table of contents generation
--no-breaks Disable automatic line break conversion (nl2br)
--no-line-numbers Disable line numbers in code blocks
--no-convert-md-links Disable converting local .md links to .html
--home-link Add a home link (🏠 >) before the title
--offline Embed JavaScript libraries for offline use
--clear-cache Clear cached library files and exit
-q, --quiet Suppress output messages
-v, --version Show program's version number and exit
usage: mk2pdf [-h] [-o FILE] [-t TITLE] [--theme {light,dark}] [--no-mermaid]
[--no-toc] [--no-breaks] [--no-line-numbers]
[--page-size {a4,letter,legal}] [--margin MARGIN] [--landscape]
[-q] [-v]
INPUT
Convert Markdown to PDF via HTML rendering.
positional arguments:
INPUT Input Markdown file (use "-" for stdin)
options:
-h, --help Show this help message and exit
-o FILE, --output FILE
Output PDF file (default: input filename with .pdf)
-t TITLE, --title TITLE
Document title
--theme {light,dark} Theme for rendering (default: light)
--no-mermaid Disable Mermaid diagram support
--no-toc Disable table of contents generation
--no-breaks Disable automatic line break conversion
--no-line-numbers Disable line numbers in code blocks
--page-size {a4,letter,legal}
PDF page size (default: a4)
--margin MARGIN Page margins in CSS format (default: 20mm)
--landscape Use landscape orientation
-q, --quiet Suppress output messages
-v, --version Show program's version number and exit
The tool supports all Mermaid diagram types. Simply use fenced code blocks with mermaid language:
```mermaid
flowchart TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
``````mermaid
sequenceDiagram
Alice->>Bob: Hello Bob!
Bob-->>Alice: Hi Alice!
``````mermaid
pie title Project Distribution
"Development" : 45
"Testing" : 25
"Documentation" : 15
"Other" : 15
``````mermaid
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Task 1 :a1, 2024-01-01, 30d
Task 2 :after a1, 20d
```Code blocks are automatically highlighted with language detection:
```python
def hello_world():
print("Hello, World!")
```
```javascript
const greet = (name) => {
console.log(`Hello, ${name}!`);
};
```Supported languages include: Python, JavaScript, TypeScript, Java, C, C++, Go, Rust, Ruby, PHP, SQL, HTML, CSS, JSON, YAML, Bash, and many more.
The generated HTML includes both light and dark themes:
- Light Theme: Clean white background with blue accents
- Dark Theme: Dark slate background with softer colors
Users can toggle between themes using the switch in the header. The preference is saved in localStorage.
mk2html/
├── .github/
│ └── workflows/
│ ├── release.yml # PyPI release & GitHub Pages deployment
│ └── tests.yml # CI test workflow
├── docs/ # Documentation (deployed to GitHub Pages)
│ ├── index.md
│ ├── getting-started.md
│ ├── mk2html.md
│ ├── mk2pdf.md
│ ├── configuration.md
│ ├── api-reference.md
│ ├── examples.md
│ ├── contributing.md
│ └── changelog.md
├── example/
│ └── markdown/ # Example markdown files
│ ├── sample.md
│ ├── sample_with_mermaid.md
│ ├── api_documentation.md
│ ├── meeting_notes.md
│ └── technical_spec.md
├── tests/
│ ├── __init__.py
│ ├── test_mk2html.py # mk2html unit tests
│ └── test_mk2pdf.py # mk2pdf unit tests
├── mk2html.py # Main HTML converter CLI
├── mk2pdf.py # PDF converter CLI
├── pyproject.toml # Package configuration
├── requirements.txt # Python dependencies
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # MIT License
└── README.md # This file
| Package | Version | Description |
|---|---|---|
| markdown | ≥3.4.0 | Markdown parsing |
| Pygments | ≥2.15.0 | Syntax highlighting (backup) |
The generated HTML loads these from CDN:
- Mermaid.js v10 - Diagram rendering
- Highlight.js v11.9 - Syntax highlighting
Convert the sample file:
python3 mk2html.py sample_with_mermaid.md -o demo.html --title "Demo Document"Then open demo.html in your browser.
Contributions are welcome! Please see our Contributing Guidelines for details on:
- Code of Conduct
- Development setup
- Pull request process
- Coding standards
Quick start for contributors:
git clone https://github.com/km1790/mk2html.git
cd mk2html
pip install -e ".[dev]"
pytest tests/ -vMIT License - feel free to use this tool for any purpose.
- Python-Markdown for Markdown parsing
- Mermaid.js for diagram rendering
- Highlight.js for syntax highlighting
- Design inspired by modern documentation sites
Made with ❤️ by Kinshuk