Markdown to HTML5

mdo

A small Rust CLI that turns Markdown into standalone HTML, with embedded simple.css styling and an open-in-browser workflow for local files.

cargo install mdo-cli
Releases Source
Binary: mdo Package: mdo-cli License: MIT or Apache-2.0
sample.md rendered by mdo

Why mdo?

Markdown is excellent for authoring and diffs, but long local Markdown files are calmer to read as browser-rendered HTML.

There are countless Markdown-to-HTML converters available, so why make another one and risk becoming another xkcd:927 footnote?

I could not find a simple, fast, and self-contained solution. Everything I looked at wanted to be a full-featured editor, relied on node or python in PATH, or needed another runtime dependency. md2htmlx was close, but every day I read dozens to hundreds of Markdown files, and reading them as HTML is richer and calmer.

mdo plus file-manager integration creates disposable HTML pages quickly enough that opening Markdown can feel like opening a text file. That means fewer generated artifacts in source folders and fewer agent-workflow prompts that spend tokens asking for an HTML report.

01 Fast local reading

Render and open Markdown from your desktop or shell without waiting on a runtime stack.

02 Throw-away friendly

--open writes to a stable temp path, so source folders stay clean by default.

03 Self-contained output

Generated pages include their own styling and work offline with no network assets.

Install

The Rust package is named mdo-cli because the bare mdo crate name is already occupied. The installed command is still mdo.

Cargo

cargo install mdo-cli
mdo --version

GitHub Releases

Download native archives for Linux, Windows, and macOS from the release page, then verify them with SHA256SUMS.

From Source

gh repo clone maphew/mdo
cd mdo
cargo build --release

Usage

By default, mdo writes a styled HTML file beside the source Markdown file. Use --open to render into a stable temp path and launch the default browser.

Common commands

mdo notes.md
mdo notes.md -o public/notes.html
mdo --bare notes.md
mdo --watch notes.md
mdo --open notes.md

What the output includes

  • HTML5 document shell with responsive viewport metadata
  • Embedded simple.css, so output files work offline
  • Tables, footnotes, task lists, and strikethrough
  • Title derived from the first top-level heading
  • Light/dark theme toggle in styled output

File Manager Integration

Open Markdown files from the desktop without leaving generated HTML beside the source file. Every integration launches the same mdo --open render-and-open path.

Windows Explorer

powershell -ExecutionPolicy Bypass -File .\scripts\install-explorer.ps1
  • Right-click a .md file and choose Open as HTML; on Windows 11 it may be under Show more options.
  • Open with offers Open as HTML.
  • If Open as HTML is made the default handler, double-click opens the browser with no console-window flash.

Linux File Managers

./scripts/install-linux-file-manager.sh
./scripts/install-linux-file-manager.sh --set-default
  • Most XDG file managers show Open With → Open as HTML for Markdown files.
  • GNOME Files/Nautilus uses the same Open With entry; no duplicate Scripts item is installed.
  • With --set-default, double-clicking Markdown files launches the browser.

macOS Finder

for file in "$@"; do
  /path/to/mdo --open "$file"
done
  • No bundled installer yet; create an Automator Quick Action that receives files in Finder.
  • Add Run Shell Script, pass input as arguments, and use the absolute path to mdo.
  • Save it as Open as HTML so Finder exposes it under Quick Actions.

Apple reference: Quick Action workflows and Run Shell Script.

Result Examples

Each path below is stable for the source file, so reopening the same Markdown overwrites the same rendered page instead of accumulating generated files.

Windows  %TEMP%\mdo\<hash>\notes.html
Linux    /tmp/mdo/<hash>/notes.html
macOS    $TMPDIR/mdo/<hash>/notes.html

Migration From md2htmlx

mdo is the independent continuation of the original md2htmlx fork. The rename changes package and binary names, plus temp output and file-association paths.

Before upgrading Windows integration

Run the old version's scripts/uninstall-explorer.ps1 if you previously installed Explorer integration. The new uninstaller also removes legacy registry entries when present.

Name changes

  • md2htmlx command becomes mdo
  • md2htmlx-open wrapper becomes mdo-open
  • %TEMP%\md2htmlx\ becomes %TEMP%\mdo\
  • Crate install path becomes cargo install mdo-cli

Project Links

Release notes, architecture decisions, source code, and package metadata are all kept in the public repository.

GitHub Releases Public Metrics Changelog Rename ADR Distribution ADR Tooling ADR docs.rs Issues