mdreader

A CLI that turns a folder of Markdown files into a polished local docs site with sidebar navigation, full-text search, syntax highlighting, Mermaid diagrams, and live reload. Built on Fumadocs.

bun add -g mdreader
pnpm add -g mdreader
npm install -g mdreader

Or run without installing: bunx mdreader ./docs --open

Quick Start

mdreader ./docs --open            # serve a docs directory and open in browser
mdreader ./docs --watch --open    # serve with live reload
mdreader ./README.md              # serve a single markdown file
mdreader doctor ./docs            # validate your docs tree
mdreader build --source ./docs --dest ./mdreader-dist  # build a static site

No configuration is needed. If you want a custom title, description, or theme, add an optional mdreader.json or run mdreader init.

Commands

mdreader [target]

Serve a directory or single Markdown file. This is the default command.

Flag	Alias	Description
--host <host>		Bind to a specific host or interface
--port <number>	-p	Port to serve on (default: auto-detect from 4000)
--open	-o	Open in browser after starting
--watch	-w	Watch for file changes and live reload
--title <title>		Override the site title for this run
--theme <theme>		Override the configured theme for this run
--include <glob>		Only include files matching a glob pattern (repeatable)
--exclude <glob>		Exclude files matching a glob pattern (repeatable)

mdreader ./docs --host 0.0.0.0 --port 8080
mdreader ./docs --include 'guides/**' --exclude '**/drafts/**'

mdreader serve [target] is an explicit alias for this command.

mdreader build

Build a deployable static site to disk. The destination directory must not already exist.

Flag	Description
--source <path>	Markdown file or docs directory to build (required)
--dest <dir>	Output directory (required)
--title <title>	Override the site title
--theme <theme>	Override the configured theme
--include <glob>	Only include files matching a glob (repeatable)
--exclude <glob>	Exclude files matching a glob (repeatable)

The output is a directory of static files that can be served by any static file server.

mdreader doctor [target]

Validate your docs setup. Checks:

• Config loading and field validation
• Content discovery and parsing
• Unsupported .mdx files
• Client asset availability
• Port availability

Flag	Description
--include <glob>	Only include files matching a glob (repeatable)
--exclude <glob>	Exclude files matching a glob (repeatable)

Exits with code 1 if any check fails. It also warns when a docs directory does not have a root landing page file (index.md, INDEX.md, or README.md).

mdreader init [target]

Create a starter mdreader.json.

Flag	Alias	Description
--title <title>		Initial site title
--description <desc>		Initial site description
--theme <theme>		Initial site theme
--force	-f	Overwrite an existing mdreader.json

mdreader init ./docs --theme ocean --title 'My Docs'

Configuration

mdreader works without configuration. To customize, add a mdreader.json in your content directory:

{
  "title": "My Project",
  "description": "Project documentation",
  "theme": "ocean"
}

Field	Default	Description
title	Directory name	Site title shown in the sidebar header
description	""	Site description used in metadata
theme	neutral	Color theme (see below)

Themes

Available values: neutral, ocean, purple, catppuccin, dusk, emerald, ruby, solar, black, shadcn, vitepress, aspen

Dark mode is automatic and follows your system preference.

Writing Content

mdreader works with regular .md files. MDX is not supported.

Frontmatter

---
title: Getting Started
description: How to set up your project
order: 1
---

Field	Default	Description
title	First <h1> or filename	Page title
description	""	Shown below the title and in search
order	999	Sort position in the sidebar; items with the same order are sorted alphanumerically, and the home page stays pinned first unless it has its own order

Supported features

• GitHub Flavored Markdown (tables, task lists, strikethrough, autolinks)
• Fenced code blocks with syntax highlighting (via Shiki)
• Mermaid diagram code fences (with expand/zoom)
• GitHub-style callouts: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION]
• Nested directory trees with index.md as the preferred folder landing page, with INDEX.md and README.md as fallbacks when index.md is missing
• Full-text search with Cmd+K / Ctrl+K
• Per-page actions menu (copy link, print, export as Markdown/HTML/JSON)

Ignored directories

These directories are always skipped during content scanning: .cache, .git, .next, .react-router, .source, build, dist, mdreader-dist, node_modules.

API Endpoints

The server exposes data and export endpoints for automation and integrations.

Data

Endpoint	Description
/api/tree.json	Sidebar navigation tree
/api/page/<slug>	Page data (title, description, segments, TOC)
/api/search-index.json	Full search index
/api/search?query=<q>	Live search results (serve mode only)

Export

Endpoint	Description
/api/export/page/<slug>.md	Page as Markdown
/api/export/page/<slug>.html	Page as standalone HTML
/api/export/page/<slug>.json	Page as JSON
/api/export/site.json	Full site export
/api/export/search?query=<q>&format=json	Search results export (serve mode only)