markserv

markserv opens local Markdown files and docs folders in your browser as a lightweight live-preview web app.

Point it at a README, notes directory, or docs tree and you get a clean GitHub-style reading view with live reload, sidebar navigation, heading anchors, syntax highlighting, Mermaid diagrams, and theme switching.

Why markserv?

• GitHub-flavored Markdown rendering via cmarkgfm
• Live reload while editing local docs
• Cmd/Ctrl+K quick search across pages, headings, and body text
• Sidebar navigation for directory-based docs
• Automatic heading anchors for deep-linking
• Syntax highlighting for fenced code blocks
• Mermaid diagram rendering for mermaid fenced code blocks
• YAML front matter for titles and nav metadata
• Safer asset serving defaults for linked local files
• System, light, and dark theme support with saved preference

Install

Requires Python 3.11+

Quick start

Serve a docs directory

markserv docs/

Serve a single Markdown file

markserv README.md

Run the built-in demo site

markserv.demo

Common variations

What it does

• Renders common Markdown extensions like .md and .markdown
• Watches Markdown files and reloads the browser when content changes
• Supports multiple concurrent instances by choosing the next free default port when needed
• Supports Cmd/Ctrl+K quick search across page titles, headings, paths, and body text
• Respects .gitignore while scanning, so ignored trees like .venv/ are skipped
• Serves linked local assets from the same file tree with safer defaults for hidden, executable, and sensitive files
• In directory mode, shows a sidebar for browsing multiple Markdown pages
• Adds heading anchors automatically for easy deep-linking
• Syntax-highlights fenced code blocks
• Renders Mermaid diagrams from mermaid fenced code blocks
• Supports YAML front matter for page titles and navigation labels/order
• Remembers your theme choice in browser storage

Front matter

markserv supports YAML front matter for page and navigation metadata:

---
title: Overview
nav_label: Start Here
nav_order: 10
hidden: false
---

# Overview

Tech stack

markserv uses:

• cmarkgfm for GitHub-flavored Markdown rendering
• FastAPI for the local web app
• FastHX for HTMX-aware FastAPI rendering
• htmy for Python component-based HTML rendering
• github-markdown-css for GitHub-like styling
• Mermaid for diagram rendering
• watchfiles for live reload
• ignoretree to respect .gitignore rules while scanning

Development

Install dev tooling:

make install

Common commands:

Notes

• markserv is intended for plain Markdown / GFM-style docs, not MDX.
• UI components are rendered with htmy from Python.
• Front-end assets live under src/markserv/public/.
• Bundled CSS comes from github-markdown-css and generated Pygments themes.
• Mermaid runtime files are vendored into src/markserv/public/vendor/ and included in built wheels and sdists.
• npm is only needed by maintainers who are updating the vendored Mermaid files with make update-mermaid.
• Bundled HTMX assets are used for SSE-driven live updates.
• The upstream stylesheet license is included at src/markserv/public/licenses/github-markdown-css.LICENSE.
• The bundled HTMX license is included at src/markserv/public/licenses/htmx.LICENSE.
• The bundled Mermaid license is included at src/markserv/public/licenses/mermaid.LICENSE.