mdo

Markdown to HTML5

A fast lightweight command-line tool written in Rust that converts Markdown into HTML, with optional file-manager integration for immediate on-the-fly viewing. The CLI supports live watch mode to automatically re-render whenever the Markdown file is edited.

cargo install mdo-cli

Binary: mdo
Package: mdo-cli
License: MIT or Apache-2.0

sample.md rendered by mdo

Release Notes Draft

mdo turns Markdown into a standalone HTML5 document with embedded styling.

Open in Browser

• Convert Markdown once and exit
• Open rendered output in the default browser
• Publish the first independent release

Commands

Task	Command
Install	cargo install mdo-cli
Convert	mdo notes.md
Open	mdo --open notes.md

Open the live sample preview.

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

Install

Start with the hosted installer unless you already use Rust. It fetches the latest GitHub Release, verifies SHA256SUMS, and installs mdo into a user-local bin directory.

Linux and macOS

curl -fsSL https://maphew.github.io/mdo/install.sh | sh

Installs to $HOME/.local/bin by default. Set MDO_INSTALL_DIR first to choose another directory.

Windows PowerShell

irm https://maphew.github.io/mdo/install.ps1 | iex

Installs to %LOCALAPPDATA%\mdo\bin by default and adds that directory to your user PATH when needed. After installation, double-click mdo-setup.exe for guided first-time configuration.

Cargo for Rust developers

cargo install mdo-cli
mdo --version

Cargo builds from source, so native downloads are usually simpler for non-Rust users.

Manual archives

Release archives and SHA256SUMS are available from GitHub Releases. Linux and Windows archives include the setup helper for guided file-manager integration.

First-time Setup

The cautious path is built in: learn what mdo will do before changing any file-manager setting.

Explore first

mdo --setup
mdo --help
mdo --open notes.md

Setup explains the render-and-open workflow, the normal convert-once command, and the reversible integration commands.

Opt in when ready

Running mdo with no arguments prints a short Open Markdown as HTML landing page and exits successfully; use mdo --help for the full CLI reference. Run mdo --setup when you want guided setup. On Windows and Linux it can offer to install Open as HTML for the current user only. The default answer is Yes, but mdo still does not change the default Markdown app. Choose No to skip or run setup again later.

After you press Enter to finish setup, mdo opens a short welcome sample so you can immediately verify the browser-opening flow. On Windows, double-click mdo-setup.exe to open that same guided setup in a fresh Windows Terminal (wt) window, falling back to a plain new console if wt is unavailable. On Linux, launch mdo Setup from your application menu or run mdo-setup to open guided setup in your $TERMINAL or a known terminal emulator (gnome-terminal, konsole, xterm, and others); it is also what mdo-open runs when launched with no file. Running it repairs its per-user application-menu entry if needed.

On Windows, launching mdo-open.exe directly with no file opens the same guided setup in a fresh Windows Terminal (wt) window using the One Half Light color scheme, centered on the active display; if wt is unavailable, it falls back to a plain new console.

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 --setup
mdo notes.md
mdo notes.md -o public/notes.html
mdo --css my-overrides.css notes.md
mdo --css restore-simple-css.css notes.md
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 plus calmer mdo heading defaults
• Optional --css overrides appended after defaults
• Release CSS to restore the vendored simple.css typography
• Tables, footnotes, task lists, and strikethrough
• Title derived from the first top-level heading
• Light/dark theme toggle in styled output

Imaginative Markdown + CSS

The project site dogfoods mdo by building a visual preview without raw HTML embeds or iframes. The source is only normal Markdown:

![Desktop background](assets/mammoth-bluefinhero-1024x695.jpg)

> sample.md rendered by mdo
>
> # Release Notes Draft
>
> `mdo` turns Markdown into a standalone HTML5 document.

The docs CSS override recognizes that generated shape and styles the blockquote as a faux browser window floating over the image:

main > p:has(> img[src$="mammoth-bluefinhero-1024x695.jpg"]) + blockquote {
  margin-top: -460px;
  background: white;
  box-shadow: 0 16px 36px rgba(7, 18, 24, 0.3);
}

That trick keeps the content portable and readable as Markdown while using --css to create a richer static page. It is a good example of how mdo can be used imaginatively: write semantic Markdown first, then layer presentation on top when the rendered page needs to tell a visual story.

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

mdo-setup.exe
mdo.exe --install-file-manager
mdo.exe --uninstall-file-manager

• 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.
• If mdo-open.exe is next to mdo.exe, it is used for flash-free Explorer launches; otherwise the single mdo.exe binary still works.
• mdo-setup.exe and no-file mdo-open.exe open guided setup in a fresh wt window with the One Half Light color scheme and center it on the active display, falling back to a plain new console when wt cannot be started.
• Windows Open With should show the friendly name Open as HTML with the mdo icon instead of exposing the wrapper file name.

Linux File Managers

mdo-setup
mdo --install-file-manager
mdo --install-file-manager --set-default
mdo --uninstall-file-manager

• The hosted installer registers a visible mdo Setup application-menu entry at ~/.local/share/applications/mdo-setup.desktop; running mdo-setup repairs it for Cargo or Homebrew installs. It is separate from the hidden mdo.desktop file handler and remains after mdo --uninstall-file-manager.
• mdo-setup opens the same first-run setup in a terminal window (your $TERMINAL or a known emulator such as gnome-terminal, konsole, or xterm); if none is found it shows a zenity/kdialog/yad notice pointing to mdo --setup.
• 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.
• Launching mdo-open with no file opens mdo-setup when present.

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-{uid}/{hash}/notes.html
macOS    $TMPDIR/mdo/{hash}/notes.html

Project Links

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

mdo is dual-licensed under MIT or Apache-2.0 and forked with gratitude from Hafiz Ali Raza's original Markdown-to-HTML CLI.