mk2html 1.4.0
Convert Markdown to beautiful, interactive HTML and PDF with TOC, dark/light mode, Mermaid diagrams, and syntax highlighting
License: MIT
Requires Python: >=3.9
Keywords: converter, dark-mode, html, markdown, mermaid, pdf, syntax-highlighting, table-of-contents, toc

# 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.

[![Tests](https://github.com/km1790/mk2html/actions/workflows/tests.yml/badge.svg)](https://github.com/km1790/mk2html/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/mk2html)](https://pypi.org/project/mk2html/)
[![Python](https://img.shields.io/pypi/pyversions/mk2html)](https://pypi.org/project/mk2html/)
[![codecov](https://codecov.io/github/km1790/mk2html/graph/badge.svg?token=6FV2NJNJ68)](https://codecov.io/github/km1790/mk2html)
[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)

📖 **[Documentation](https://km1790.github.io/mk2html/)** | 🚀 **[PyPI](https://pypi.org/project/mk2html/)** | 📝 **[Changelog](CHANGELOG.md)**

## ✨ 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:**

```bash
# HTML converter only
pip install mk2html

# With PDF support
pip install mk2html[pdf]
```

**Install as global CLI tool with uv:**

```bash
uv tool install mk2html
```

**Install from source:**

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

## ⚡ Quick Start

**Convert a Markdown file to HTML:**

```bash
mk2html README.md
```

This creates `README.html` in the same directory.

**Convert with custom output:**

```bash
mk2html docs.md -o documentation.html
```

**Convert to PDF (requires `mk2html[pdf]`):**

```bash
mk2pdf README.md -o README.pdf
```

**Convert from stdin:**

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

**Batch convert all markdown files:**

```bash
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

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

### Sequence Diagram

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

### Pie Chart

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

### Gantt Chart

````markdown
```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:

````markdown
```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](https://mermaid.js.org/) v10 - Diagram rendering
- [Highlight.js](https://highlightjs.org/) v11.9 - Syntax highlighting

## 📝 Example

Convert the sample file:

```bash
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](CONTRIBUTING.md) for details on:

- Code of Conduct
- Development setup
- Pull request process
- Coding standards

**Quick start for contributors:**

```bash
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](https://python-markdown.github.io/) for Markdown parsing
- [Mermaid.js](https://mermaid.js.org/) for diagram rendering
- [Highlight.js](https://highlightjs.org/) for syntax highlighting
- Design inspired by modern documentation sites

---

Made with ❤️ by Kinshuk