mdx

A fast, single-binary markdown toolchain built in Rust. Render in the terminal with syntax highlighting, preview in the browser with live reload, search, fetch web pages, format, lint, diff, export to HTML/PDF/EPUB, and publish — all from one command.

By Anurag Vishwakarma ·

Install #

bashcurl -fsSL https://raw.githubusercontent.com/Harsh-2002/mdx/main/install.sh | shCopy

powershellirm https://raw.githubusercontent.com/Harsh-2002/mdx/main/install.ps1 | iexCopy

bashcargo install --git https://github.com/Harsh-2002/mdx --features serveCopy

Installs the binary and sets up shell completions automatically. Works on macOS, Linux (glibc and musl), and Windows. Supports x86_64 and ARM64.

Pre-built binaries

Each release includes pre-built binaries for every supported platform. Download the one that matches your system:

Extract and move the binary to a directory in your PATH:

bashtar xzf mdx-<target>.tar.gz
sudo mv mdx /usr/local/bin/Copy

Quick Start #

bashmdx README.md                          # render in terminal
mdx README.md --pager                  # pipe through less
mdx serve file.md                      # live preview in browser
mdx serve ./notes/                     # serve a directory of notes
mdx search "query" ./docs/             # full-text search across files
mdx fetch https://example.com          # fetch web page as markdown
mdx export --to epub file.md           # export to EPUB e-book
mdx update                             # self-update to latest version
cat README.md | mdx                    # read from stdin
mdx https://example.com/doc.md         # render from URLCopy

Features #

• Syntax highlighting — language-aware code blocks via syntect
• Tables — full GFM table rendering with alignment and cell wrapping
• Docs extensions — description lists, ==highlight==, ^superscript^, [[wikilinks]] and inline footnotes, on top of GFM — each rendering in every output target
• Mermaid diagrams — rendered as interactive SVG in browser preview (mdx serve) via mermaid.js
• Math — inline $...$ and display $$...$$; KaTeX in browser preview, Unicode in the terminal (\frac{a}{b} renders as a/b)
• Images — inline image rendering in supported terminals (iTerm2, kitty)
• URL fetching — mdx <url> and mdx fetch <url> share one pipeline: markdown URLs render as markdown, web pages have their article extracted
• Web page extraction — mdx fetch extracts article content as clean markdown, with MFA content negotiation
• Markdown for Agents — mdx serve responds with raw markdown when AI agents send Accept: text/markdown
• Live reload — mdx serve opens a browser preview that updates on save
• Built-in editor — edit markdown in the browser, saves back to disk
• Search & replace — find and replace text in the editor with regex support
• Image upload — drag and drop or paste images into the editor
• Print / PDF — native PDF export, plus browser print with clean CSS
• Reproducible PDFs — the same document always exports to the same bytes, with subset fonts keeping files small and SOURCE_DATE_EPOCH honoured
• Structured fetch — mdx fetch --json reports status, extraction method, token count and warnings alongside the markdown; --max-tokens trims to a context window
• EPUB export — mdx export --to epub for Apple Books, Kobo, Calibre, and other e-readers
• Full-text search — mdx search with BM25 ranking, tag filtering, and parallel file parsing
• Dark/light theme — toggle with button or t, persisted across sessions
• Slide presentation — mdx present turns --- separators into terminal slides
• ToC generation — mdx toc extracts headings with depth control
• Self-update — mdx update updates to the latest release
• Shell completions — mdx completions install for bash, zsh, fish, PowerShell
• Alerts — GitHub-style note, tip, warning, and caution blocks
• Full GFM — footnotes, task lists, strikethrough, autolinks

CLI Tools #

bashmdx fetch https://example.com              # extract article as markdown
mdx fetch --raw https://example.com        # full HTML to markdown (sanitizes scripts)
mdx fetch --metadata https://example.com   # include YAML front matter
mdx fetch --tokens https://example.com     # show estimated token count
mdx fetch -o article.md https://example.com  # save to file
mdx fetch --json https://example.com | jq -r .content   # structured output
mdx fetch --json --max-tokens 4000 URL     # fit a context window
mdx fetch https://example.com | llm        # pipe to LLMCopy

bashmdx toc README.md              # print table of contents
mdx toc --depth 2 README.md    # limit to h1 and h2Copy

$ mdx stats README.md
     Words: 1,247
     Lines: 89
  Headings: 12
     Links: 8
Code blocks: 3
Reading time: ~5 minCopy

bashmdx fmt README.md                # print formatted to stdout
mdx fmt --in-place README.md     # overwrite the file
mdx fmt --check README.md        # exit 1 if not formatted (CI)Copy

$ mdx lint README.md
  README.md:12 broken link: ./missing.md
  README.md:34 image missing alt text
  README.md:45 duplicate heading: "Setup"
  3 issues foundCopy

bashmdx diff old.md new.md           # side-by-side
mdx diff -u old.md new.md        # unified
mdx diff - new.md                # read first file from stdinCopy

bashmdx search "rust async" .            # search current directory
mdx search "query" docs/              # search recursively
mdx search --tag rust "ownership"    # filter by front matter tag
mdx search -n 5 "error" .            # top 5 results
mdx search -l "query" .              # list matching file paths onlyCopy

bashmdx export --to html README.md   # single-file HTML page
mdx export --to pdf README.md    # PDF (native, no browser needed)
mdx export --to epub README.md   # EPUB e-book
mdx export --to json README.md   # AST as JSON (for tooling)
mdx export --to txt README.md    # plain text (strip formatting)Copy

bashmdx publish ./blog --out ./distCopy

bashmdx updateCopy

bashmdx completions install              # auto-detect shell and install
mdx completions bash                 # print bash completions
mdx completions zsh                  # print zsh completions
mdx completions fish                 # print fish completions
mdx completions powershell           # print PowerShell completionsCopy

bashmdx present slides.mdCopy

bashmdx watch file.mdCopy

Serve Mode #

mdx serve turns your markdown into a live browser preview with three modes:

Single file — mdx serve file.md opens a live preview. Edit in your editor, the browser updates instantly on save.

Directory — mdx serve ./notes/ shows all .md files as a card grid. Click any card to view it, or click "+" to create a new note.

Multiple files — mdx serve a.md b.md c.md mdx serve file.md --host 0.0.0.0 # expose on your LAN mdx serve file.md --unsafe-html # render raw HTML in the document serves the listed files with sidebar navigation and search.

All modes include a built-in editor, image upload (drag and drop or paste), print/PDF export, dark/light theme, and a table of contents sidebar. AI agents sending Accept: text/markdown get raw markdown with X-Markdown-Tokens and Vary: Accept headers instead of HTML (Markdown for Agents protocol).

Local images are served from the document's directory, so ![](assets/shot.png) renders — including files the drag-and-drop uploader writes.

Security defaults

The server is unauthenticated: anyone who can reach the port can read your files, overwrite them, create new ones and upload into assets/. So it is locked down by default.

• Binds 127.0.0.1 — reachable only from this machine. --host 0.0.0.0 exposes it to your network.
• Answers only on an address — 127.0.0.1, ::1, localhost or a LAN IP, never a domain name. Binding loopback alone does not stop a web page pointing a domain at 127.0.0.1 and reaching the server through your browser; requiring an address in the Host header does. Writes carrying a cross-origin Origin are refused.
• Raw HTML is dropped — a <script> in a downloaded or agent-written document cannot run. --unsafe-html renders it the way GitHub does: <div> and <details> pass, <script> and <iframe> stay neutralised.

mdx export is different: it writes a file you open yourself, so it converts your document faithfully, tags and all.

How It Works #

mdx parses markdown into an AST using comrak (CommonMark + GFM), then walks the tree to produce either styled terminal output with ANSI escape codes, or HTML served via a local server with SSE-based live reload.

markdown file
      |
      v
   comrak  -->  AST
      |
      |-->  terminal renderer  -->  ANSI output
      |
      |-->  HTML renderer  -->  axum server  -->  browser (live reload via SSE)
      |
      '-->  CLI tools (stats, toc, fmt, lint, diff, search, export, fetch, publish)

Credits #

mdx is built on top of these open-source libraries: