mk2html 1.3.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.

✨ 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

📦 Installation

Prerequisites

• Python 3.7 or higher
• pip (Python package manager)

Install Dependencies

pip install -r requirements.txt

Or install manually:

pip install markdown Pygments

Make Executable (Optional)

chmod +x mk2html.py

Create Global Symlink (Optional)

ln -s $(pwd)/mk2html.py /usr/local/bin/mk2html

🚀 Usage

Basic Usage

python3 mk2html.py input.md

This creates input.html in the same directory.

Specify Output File

python3 mk2html.py docs.md -o documentation.html

Custom Title

python3 mk2html.py guide.md --title "User Guide"

Start with Dark Theme

python3 mk2html.py report.md --theme dark

Disable Mermaid Support

python3 mk2html.py spec.md --no-mermaid

Read from Stdin

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

Quiet Mode (for scripts)

python3 mk2html.py input.md -q

Full Options

python3 mk2html.py --help

usage: mk2html [-h] [-o FILE] [-t TITLE] [--theme {light,dark}] [--no-mermaid]
               [--no-toc] [-q] [-v]
               INPUT

Convert Markdown to beautiful, interactive HTML with TOC and Mermaid support.

positional arguments:
  INPUT                 Input Markdown file (use "-" for stdin)

optional arguments:
  -h, --help            show this help message and exit
  -o FILE, --output FILE
                        Output HTML file (default: input filename with .html extension)
  -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
  -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/
├── mk2html.py              # Main CLI tool
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── SESSION.md             # Development session log
├── sample.md              # Sample markdown file
├── sample_with_mermaid.md # Sample with Mermaid diagrams
└── *.html                 # Generated output files

🔧 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 feel free to submit issues or pull requests.

📄 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