Markdown to HTML cmd-line tool

A powerful command-line tool to convert Markdown files to HTML with GitHub-style CSS. Built with Go and featuring batch processing, validation, and shell completion support.

Features

• Single file conversion - Convert individual Markdown files to HTML
• Batch processing - Convert multiple files at once with pattern matching
• Recursive processing - Process entire directory trees
• Validation - Check Markdown syntax without generating output
• Shell completion - Auto-completion for bash and zsh
• GitHub-style CSS - Beautiful GitHub-inspired styling
• Smart typography - Optional smart quotes, dashes, and fractions

Quick Start

# Convert a single file
mdtohtml README.md README.html

# Batch convert all .md files in a directory
mdtohtml batch ./docs --out-dir ./html

# Validate Markdown syntax
mdtohtml validate document.md

Usage

Convert Command (Default)

Convert a single Markdown file to HTML:

# Default command (can omit 'convert')
mdtohtml input.md output.html

# Explicit convert command
mdtohtml convert input.md output.html

# With options
mdtohtml input.md output.html --smartypants=false --latexdashes=false

Typography options (apply to all commands):

| Flag | Default | Effect | |------|---------|--------| | --smartypants | true | "x" to \u201cx\u201d, 'x' to \u2018x\u2019, ... to \u2026 | | --latexdashes | true | --- to em-dash (\u2014), -- to en-dash (\u2013). When false: -- to em-dash, - between words to en-dash | | --fractions | true | 1/2 to \u00bd, 1/4 to \u00bc, 3/4 to \u00be | | --safe-mode | false | Strip raw HTML to prevent XSS |

These options are powered by the Goldmark typographer extension.

Batch Command

Convert multiple Markdown files at once:

# Convert all .md files in a directory
mdtohtml batch ./docs --out-dir ./html

# Use custom file pattern
mdtohtml batch ./docs --pattern "*.markdown" --out-dir ./public

# Process directories recursively
mdtohtml batch ./docs --recursive --out-dir ./output

# With typography options
mdtohtml batch ./docs --out-dir ./html --smartypants=false

Options:

• -o, --out-dir (default: ".") - Output directory for HTML files
• -p, --pattern (default: "*.md") - File pattern to match
• -r, --recursive - Process directories recursively
• Plus all typography options from convert command

Validate Command

Check Markdown syntax without generating output:

# Validate a single file
mdtohtml validate document.md

# Validate with specific parser settings
mdtohtml validate document.md --smartypants=false

Returns exit code 0 if valid, non-zero if invalid.

Shell Completion

Enable auto-completion for your shell:

# Bash
mdtohtml completion bash > /etc/bash_completion.d/mdtohtml

# Zsh
mdtohtml completion zsh > /usr/local/share/zsh/site-functions/_mdtohtml

# Fish
mdtohtml completion fish > ~/.config/fish/completions/mdtohtml.fish

# PowerShell
mdtohtml completion powershell > mdtohtml.ps1

Examples

# Convert README to HTML
mdtohtml README.md README.html

# Batch convert documentation
mdtohtml batch ./docs --out-dir ./website/docs --recursive

# Validate before committing
mdtohtml validate *.md

# Convert with plain typography
mdtohtml input.md output.html --smartypants=false --fractions=false

Library Usage

mdtohtml can also be used as a Go library. The converter package exposes two constructors:

package main

import (
	"fmt"
	"log"

	"github.com/sgaunet/mdtohtml/pkg/converter"
	"github.com/sgaunet/mdtohtml/pkg/parser"
	"github.com/sgaunet/mdtohtml/pkg/template"
)

func main() {
	// Use default components
	conv := converter.NewCompleteConverter(converter.DefaultOptions())
	html, err := conv.Convert([]byte("# Hello\n\nWorld"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(html))

	// Or inject custom components (title extractor, HTML template)
	gc := converter.NewGoldmarkConverter(converter.DefaultOptions())
	te := parser.NewMarkdownTitleExtractor()
	ht := template.NewGitHubTemplate()

	custom := converter.NewCompleteConverterWithComponents(gc, te, ht)
	html, err = custom.Convert([]byte("# Custom\n\nWith custom components"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(html))
}

Implement the parser.TitleExtractor or template.HTMLTemplate interfaces to replace the defaults with your own logic.

Docker Image

There is a docker image to integrate the binary into your own docker image for example.

For example, the Dockerfile should look like :

FROM sgaunet/mdtohtml:latest AS mdtohtml

FROM <BASE-IMAGE:VERSION>
...
COPY --from=mdtohtml /usr/bin/mdtohtml /usr/bin/mdtohtml
...

Supported Markdown Features

mdtohtml uses the Goldmark parser with the following extensions:

• GitHub Flavored Markdown (GFM) - Tables, strikethrough, autolinks, task lists
• Definition Lists - Support for <dl>, <dt>, <dd> elements
• Footnotes - Reference-style footnotes
• Typographer - Smart quotes, dashes, fractions (when enabled)
• Auto heading IDs - Automatic generation of heading anchors
• Unsafe HTML - Raw HTML is preserved

Installation

Install with Homebrew

brew tap sgaunet/homebrew-tools
brew install sgaunet/tools/mdtohtml

Manual Installation

Download the latest release from the releases page and copy it to /usr/local/bin or any directory in your PATH.

Build from source

# Clone the repository
git clone https://github.com/sgaunet/mdtohtml.git
cd mdtohtml

# Build with task (recommended)
task build

# Or build directly with Go
go build .

# Install to your PATH
sudo cp mdtohtml /usr/local/bin/

Development

# Run linter
task lint

# Create snapshot build
task snapshot

# Create release
task release