mk2html 1.4.0

Convert Markdown to beautiful, interactive HTML and PDF with TOC, dark/light mode, Mermaid diagrams, and syntax highlighting

mk2html

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

✨ Features

• 🌙 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

🚀 Getting Started

Prerequisites

• Python 3.9 or higher
• pip or uv (Python package managers)

Installation

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 mk2html

Install from source:

git clone https://github.com/km1790/mk2html.git
cd mk2html
pip install -e .

⚡ Quick Start

Convert a Markdown file to HTML:

mk2html README.md

This creates README.html in the same directory.

Convert with custom output:

mk2html docs.md -o documentation.html

Convert to PDF (requires mk2html[pdf]):

mk2pdf README.md -o README.pdf

Convert from stdin:

cat input.md | mk2html - -o output.html

Batch 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 links

📋 Command Line Options

mk2html

usage: 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

mk2pdf

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

📊 Mermaid Diagrams

The tool supports all Mermaid diagram types. Simply use fenced code blocks with mermaid language:

Flowchart

```mermaid
flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

Sequence Diagram

```mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!
```

Pie Chart

```mermaid
pie title Project Distribution
    "Development" : 45
    "Testing" : 25
    "Documentation" : 15
    "Other" : 15
```

Gantt Chart

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
        Task 1 :a1, 2024-01-01, 30d
        Task 2 :after a1, 20d
```

🎨 Syntax Highlighting

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.

🌙 Theme Support

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.

📁 Project Structure

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

🔧 Dependencies

Package	Version	Description
markdown	≥3.4.0	Markdown parsing
Pygments	≥2.15.0	Syntax highlighting (backup)

External CDN Resources

The generated HTML loads these from CDN:

• Mermaid.js v10 - Diagram rendering
• Highlight.js v11.9 - Syntax highlighting

📝 Example

Convert the sample file:

python3 mk2html.py sample_with_mermaid.md -o demo.html --title "Demo Document"

Then open demo.html in your browser.

🤝 Contributing

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/ -v

📄 License

MIT License - feel free to use this tool for any purpose.

🙏 Acknowledgments

• 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