mdo

Open Markdown as HTML

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.

# Linux and macOS
curl -fsSL https://maphew.github.io/mdo/install.sh | sh

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

No Rust toolchain needed — the installer fetches and verifies the latest release binary. On Windows it updates your user PATH; on Linux/macOS it installs to ~/.local/bin by default and tells you if that directory must be added to PATH. More options (Cargo, manual archives) in the Install section below.

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	Download the release binary
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 files are more pleasant to read as browser-rendered HTML. Every day I read dozens to hundreds of Markdown files. Reading as rich text is smoother, calmer.

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

I couldn't find an existing simple, fast, and self-contained solution. Everything I discovered wanted to be a full-featured editor, relied on node or python in PATH, or needed another runtime dependency.

mdo plus file-manager integration creates disposable HTML pages quickly enough that opening Markdown can feel like opening a text file. This 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.

Android preview

The Android app is not yet available from Google Play or F-Droid. Download the signed mdo-android-arm64.apk from the latest GitHub Release, open it on your device, and approve Android's prompt to allow installation from that source. It supports 64-bit ARM devices running Android 6.0 or newer.

To build the preview from source instead, install JDK 17, Android SDK platform 36, NDK 28.2.13676358, Rust, and cargo-ndk. Then connect a device with USB debugging enabled and run:

git clone https://github.com/maphew/mdo.git
cd mdo
rustup target add aarch64-linux-android
cargo install cargo-ndk --locked
cd android
./gradlew installDebug

On Windows, use gradlew.bat installDebug. See the complete Android build and usage guide for requirements, package details, privacy information, and current limitations.

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 withoit arguments prints a short Open Markdown as HTML landing page and exits successfully; use mdo --help for full CLI reference. Run mdo --setup for guided file manager integration. On Windows and Linux offers 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 pressing Enter to finish setup, mdo opens a short welcome sample to verify the browser-opening flow.

On Windows, double-click mdo-setup.exe to open the same guided setup without a terminal; on Linux, launch mdo Setup from your application menu or run mdo-setup. Launcher details are in the file-manager integration guide.

The two methods give same results.

Usage

By default, mdo cli in terminal 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

This page — including the faux browser window floating over the hero image above — is normal Markdown rendered by mdo, with the visual story layered on through --css. It is the only page on this site with custom styling; every other page is mdo's out-of-the-box output, exactly what you get on your own machine. See Custom CSS for how --css works and the faux browser window how-to for how this page's hero is built.

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. Platform implementation details live in the file-manager integration guide.

Windows Explorer

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

• Right-click an .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 mdo-open.exe open guided setup in a fresh wt windows terminal 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-{uid}/{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, forked with gratitude from Hafiz Ali Raza's original Markdown-to-HTML CLI.