mk2html - Markdown to HTML Converter

mk2html converts Markdown files to beautiful, interactive HTML documents with modern styling, table of contents, dark/light mode, and Mermaid diagram support.

Usage

mk2html <input.md> [options]
mk2html "*" -o <output-dir> [options]    # Batch mode

Options

Option	Short	Description	Default
`--output`	`-o`	Output HTML file or directory (batch mode)	`<input>.html`
`--recursive`	`-r`	Recursively process subdirectories (batch mode only)	Disabled
`--title`	`-t`	Document title	Filename
`--theme`		Default theme (`light` or `dark`)	`light`
`--no-mermaid`		Disable Mermaid diagram support	Enabled
`--no-toc`		Disable table of contents	Enabled
`--no-line-numbers`		Disable line numbers in code blocks	Enabled
`--no-breaks`		Disable newline to `<br>` conversion	Enabled
`--no-convert-md-links`		Disable converting `.md` links to `.html`	Enabled
`--home-link`		Add home link (🏠 >) before title	Disabled
`--offline`		Embed JS libraries for offline use	Disabled
`--clear-cache`		Clear cached library files
`--quiet`	`-q`	Suppress output messages
`--version`	`-v`	Show version number
`--help`	`-h`	Show help message

Examples

Basic Conversion

mk2html README.md

Creates README.html in the same directory.

Custom Output File

mk2html docs/guide.md -o website/documentation.html

Custom Title

mk2html README.md -o index.html --title "Project Documentation"

Dark Theme by Default

mk2html README.md --theme dark

The user can still toggle between themes using the UI button.

Batch Conversion

Convert all markdown files in the current directory:

mk2html "*" -o ./html/

Recursively convert all markdown files including subdirectories:

mk2html "*" -o ./html/ -r

The directory structure is preserved in the output:

./docs/index.md       → ./html/index.html
./docs/guide.md       → ./html/guide.html
./docs/api/ref.md     → ./html/api/ref.html

Add a home link before the title for navigation:

mk2html guide.md --home-link

This adds 🏠 > Guide in the header, where 🏠 links to index.html.
The home link is automatically skipped for index.md files.

MD-to-HTML Link Conversion

By default, local markdown links are converted to HTML links:

[Getting Started](getting-started.md)

Becomes:

<a href="getting-started.html">Getting Started</a>

Disable with --no-convert-md-links.

Disable Mermaid Diagrams

mk2html README.md --no-mermaid

Reduces file size if you don't use Mermaid diagrams.

Offline Mode

mk2html README.md --offline

Embeds Mermaid.js and Highlight.js directly in the HTML file for offline viewing. File size increases (~3.5MB for Mermaid).

Disable Line Numbers

mk2html README.md --no-line-numbers

Code blocks will not have line numbers.

Standard Markdown Line Breaks

mk2html README.md --no-breaks

By default, single newlines become <br> tags. Use --no-breaks for standard Markdown behavior where you need two newlines for a paragraph break.

Read from stdin

cat README.md | mk2html - -o output.html
echo "# Hello" | mk2html - -o hello.html

Clear Library Cache

mk2html --clear-cache

Removes cached Mermaid.js and Highlight.js files from ~/.cache/mk2html/.

Features

Automatically generated from all headings (h1-h6) in your document:
- Appears in a fixed sidebar
- Highlights current section while scrolling
- Click to navigate
- Collapsible on mobile

Dark/Light Mode

Toggle button in the header
Preference saved in localStorage
Affects all elements including Mermaid diagrams

Mermaid Diagrams

Supports all Mermaid diagram types:

<div class="mermaid">
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
</div>

Supported diagram types:
- Flowcharts
- Sequence diagrams
- Class diagrams
- State diagrams
- Entity Relationship diagrams
- Gantt charts
- Pie charts
- Git graphs

Syntax Highlighting

Code blocks are automatically syntax-highlighted:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
```

Supports 190+ languages via Highlight.js.

Line Numbers

Code blocks include line numbers by default. Disable with --no-line-numbers.

Responsive Design

Sidebar collapses on mobile devices
Hamburger menu to toggle sidebar
Optimized typography for all screen sizes

Progress Bar

A reading progress bar appears at the top of the page.

Back to Top Button

Appears when you scroll down, click to return to top.

Output Structure

The generated HTML includes:

<!DOCTYPE html>
├── <head>
│   ├── Meta tags (charset, viewport, generator)
│   ├── Title
│   └── Embedded CSS (all styles inline)
├── <body>
│   ├── Progress bar
│   ├── Header (title + theme toggle)
│   ├── Sidebar (table of contents)
│   ├── Main content
│   ├── Back to top button
│   └── Scripts (Mermaid, Highlight.js, theme logic)

All CSS and JavaScript are embedded, making the HTML file self-contained.

File Size

Mode	Approximate Size
Basic (no Mermaid)	~40 KB
With Mermaid (CDN)	~45 KB
Offline mode	~3.5 MB

Library Cache

When using offline mode, libraries are cached in:

~/.cache/mk2html/
├── <hash>_mermaid.min.js
└── <hash>_highlight.min.js

Clear with mk2html --clear-cache.

🏠 > Mk2Html