markserv 1.4.4

Preview local Markdown files and doc trees with live reload, sidebar navigation, anchors, and syntax highlighting

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+

Use case	Command
Install from PyPI with uv	uv tool install markserv
Install from PyPI with pipx	pipx install markserv
Install a local checkout for development	uv tool install .

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

Command	What it does
markserv .	Serve the current directory
markserv --host localhost --port 4422 .	Bind to a custom host/port
markserv --port 0 README.md	Bind to any free port
markserv --no-open README.md	Start without opening a browser
markserv.demo --no-open --port 9001	Run the demo on a custom port

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

Key	Purpose
title	Browser/page title fallback
nav_label	Sidebar label override
nav_order	Numeric sort order in the sidebar
hidden	Hide the page from sidebar navigation while keeping it routable

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:

Task	Command
Format	make format
Check formatting	make format-check
Lint	make lint
Type-check	make typecheck
Test	make test
Run the full local CI suite	make all-ci
Install optional asset update tooling	make install-assets
Refresh vendored frontend assets	make vendor-assets
Update Mermaid and refresh the vendored asset	make update-mermaid

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.