markserv 1.0.0

Live-render GitHub-flavored markdown files and folders

markserv

markserv is a small FastAPI-based markdown preview server for local docs.

It 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
• watchfiles for live reload
• ignoretree to respect .gitignore rules while scanning

Install

Once published:

uv tool install markserv

For local development:

uv tool install .

Usage

Serve a directory of markdown files:

markserv docs/

Serve a single markdown file:

markserv README.md

Run the built-in synthetic demo site:

markserv.demo

Options:

markserv .
markserv --host localhost --port 4422 .
markserv --no-open README.md
markserv.demo --no-open --port 9001

Behavior

• Renders common markdown extensions like .md and .markdown
• Watches markdown files and reloads the browser when content changes
• Respects .gitignore while scanning so ignored trees like .venv/ are skipped
• Serves linked local assets like images from the same file tree
• In directory mode, shows a sidebar for browsing multiple markdown pages
• Includes a system/light/dark theme control that remembers your choice in browser storage

Development

Install dev tooling:

make install

Common commands:

make format
make format-check
make lint
make typecheck
make test
make all-ci

Notes

• This 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.
• 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.