webolator

Turn a folder of markdown, or a single .md file, into a browsable website. No config file, no index file, no SUMMARY.md.

Docs: https://vivainio.github.io/webolator/ (built with webolator, of course)

• Zero config. Point it at a folder and the navigation comes from the directory tree. Page titles come from the first # heading.
• Mermaid. ```mermaid blocks become diagrams, rendered in the browser.
• Syntax highlighting happens at build time (syntect), with light and dark themes and no JavaScript.
• Cross-file links work. other.md, dir/, ../x.md#some-heading and /root/relative.md are rewritten to the right pages and anchors. Broken links print a warning.
• Sibling files are kept. Raw .html, .txt/.log/code files, PDFs and images are copied and linked. HTML, text and PDF files also appear in the sidebar.
• --single writes one self-contained .html with everything embedded (images, text files, HTML files, PDFs), which is easy to email or attach.
• --serve runs a local preview with live reload.
• Reading features: an "On this page" sidebar, previous/next links, "last updated" and "Edit this page" from git, a light/dark toggle, copy buttons on code, image zoom and a mobile menu.
• Writing extras: $math$ (KaTeX), :emoji:, [[wikilinks]], and optional front matter (title, order, hidden). See the syntax reference for every supported form.
• --check fails the build on broken links, for CI.
• --files assets/ shows a folder as a plain file list (name, size, date) instead of rendering it. Useful for downloads and attachments.
• --gallery screenshots/ shows a folder of images as a thumbnail grid with click-to-zoom.
• Custom CSS. A webolator.css in the docs root is applied automatically, or you can pass --css file.css. Colors are CSS variables, so a theme can be a few lines. See styling.
• GitHub-flavored markdown: tables, task lists, footnotes, strikethrough, autolinks and > [!NOTE] alerts.
• Light and dark mode follow the OS setting.

Installation

Using uv (easiest)

Install the published wheel from PyPI as a standalone tool:

uv tool install webolator

This puts the webolator command on your PATH. To try it without installing anything:

uvx webolator docs/ --serve

Pre-built binaries

Download the latest release for your platform from the GitHub Releases page:

• Linux (x86_64): webolator-linux-x86_64.tar.gz
• Windows (x86_64): webolator-windows-x86_64.zip
• macOS (Intel): webolator-macos-x86_64.tar.gz
• macOS (Apple Silicon): webolator-macos-arm64.tar.gz

Extract the archive and place the webolator binary in your PATH.

From source

cargo install --git https://github.com/vivainio/webolator

Usage

webolator docs/                     # static site in ./site
webolator docs/ -o public           # ...or somewhere else
webolator docs/ --single            # one self-contained docs.html
webolator notes.md --single         # a single file, plus anything it links to
webolator docs/ --serve             # http://127.0.0.1:8000 with live reload

Try it on the bundled demo:

cargo run -- examples/demo --serve

How the site is put together

Number prefixes like 01-usage.md or 02-guides/ set the sidebar order. They don't appear in labels and are removed from URLs, so 02-guides/01-setup.md becomes guides/setup.html.

If you pass a single file, webolator follows its local links, including links to parent folders. The site then contains that file, which becomes the home page, plus everything reachable from it.

In --single mode, each page becomes a section with hash routing, so the back and forward buttons and deep links like docs.html#p-guide-install--setup work. Images are inlined. Linked HTML files are shown in an iframe and text files as preformatted text, and PDFs and other files open from embedded blobs.

Mermaid offline

By default mermaid.js is loaded from the jsDelivr CDN, and only on pages that contain a diagram. To work fully offline, pass a local copy:

webolator docs/ --single --mermaid-js mermaid.min.js

In static mode the file is copied to _webolator/. In --single mode it is inlined.