Getting Started

monodocs turns a directory of Markdown / AsciiDoc files into one self-contained HTML file: you keep the sources split, and only the distributed artifact is a single file.

What it produces

monodocs build ./docs -o ./dist/docs.html

The output is a single HTML with no external runtime, embedding in-page search, a table of contents, prev/next navigation, dark mode, and a print layout. The Single-file sample link in the top navigation is generated by monodocs from this project's own examples.

Searching the output

Type in the sidebar search box to search titles, headings, and body text.

• Open the box: / or Ctrl+K (⌘K on macOS) from anywhere, even with the sidebar closed (it opens first). Neither key is taken while you type in a field, so / stays typeable and Ctrl+K keeps its macOS editing meaning. ⌘K is the exception: it works in a field too and selects the current query so you can type over it.
• Keywords: separate them with spaces; a page is listed only when it contains every keyword. Results rank by where the keywords appear (title, then heading, then body), and a heading match jumps straight to that heading.
• Matching: substring-based (Japanese needs no spaces inside a keyword) and case-insensitive. Full-width alphanumerics (ＰＤＦ) match their half-width form, katakana matches hiragana (インストール finds いんすとーる), and the prolonged sound mark and dashes (ー / ―) and the wave dash and full-width tilde (〜 / ～) are treated alike. So is half-width katakana (ｶﾞｲﾄﾞ finds ガイド). A keyword also matches loosely: an English word by its stem (installing finds install), and okurigana between two kanji there or not (引き渡し finds 引渡し); a page that every keyword matches as typed comes first.
• Keyboard: ↓ / ↑ move through the results (wrapping at both ends), Enter opens the selected one (or the top one if you have not moved), and Escape clears the box. The cursor stays in the box, so you can keep typing.
• Clear: the × at the right of the box clears the query, the results, and the highlight, as Escape does, even after you have moved on to a page (on a narrow screen, open the sidebar first). The cursor goes back into the box.
• Highlight: the keywords stay highlighted in the page you open and on pages you move to after it, until you change or clear the query.

Install

monodocs is published on npm and requires Node.js 22.12.0 or later. Linux x64 and Windows x64 are the supported platforms.

npm install -g monodocs
# Or run it without a global installation
npx monodocs build ./docs -o ./dist/docs.html

To pin the version in a repository, add it to the project instead:

npm install -D monodocs

IMPORTANT

PDF output and Mermaid pre-rendering require a system-installed Chromium or Google Chrome; monodocs never downloads a browser. It is detected automatically on Linux and Windows (Windows also falls back to Chromium-based Microsoft Edge). Set PUPPETEER_EXECUTABLE_PATH for a non-standard install location or on platforms without detection, such as macOS.

Standalone binary (no Node.js)

Every release also ships a single executable that bundles the Node runtime. Download monodocs-linux-x64 or monodocs-windows-x64.exe from the Releases page with the matching .sha256 file. Each binary comes with a -NOTICES.txt file listing the licenses of everything it embeds (monodocs, its npm dependencies, and the Node.js runtime); keep it alongside the binary when you redistribute it inside your organization.

Linux x64:

sha256sum -c monodocs-linux-x64.sha256   # verify the download
chmod +x monodocs-linux-x64
./monodocs-linux-x64 build ./docs -o ./dist/docs.html

Windows x64 (PowerShell):

# Verify the download: prints True when the hashes match
(Get-FileHash .\monodocs-windows-x64.exe).Hash -eq (Get-Content .\monodocs-windows-x64.exe.sha256).Split(' ')[0]
.\monodocs-windows-x64.exe build .\docs -o .\dist\docs.html

The binary covers init, build (HTML), validate, watch, and serve. PDF output and Mermaid pre-render are not available in the binary: both drive a headless browser through puppeteer-core, which is left out of the bundle, and the command fails with a message saying so. Use the npm package for them.

NOTE

The binaries are unsigned, so Windows SmartScreen may warn on first run.

First build

Starting from nothing, init writes a configuration and a first page that build unedited:

monodocs init     # -> monodocs.config.yml, docs/index.md
monodocs build    # -> dist/docs.html

It never overwrites: if either file exists it writes neither and reports what it found, so it is safe to try in a directory that already holds work. See init for the generated configuration.

With documents you already have:

# Single self-contained HTML
monodocs build ./docs -o ./dist/docs.html

# PDF (requires Chromium)
monodocs build ./docs --format pdf -o ./dist/docs.pdf

# Report broken links, missing images, and missing titles
monodocs validate ./docs

The input directory structure becomes the sidebar; Markdown and AsciiDoc may be mixed freely.

Preview locally

# Live-reloading preview server on http://127.0.0.1:4173/
monodocs serve ./docs --open

Run from source

To work on monodocs itself, build from the repository. The toolchain runs inside Docker, so the host needs no Node or pnpm:

git clone https://github.com/kuttsun/monodocs.git
cd monodocs

scripts/app.sh pnpm install
scripts/app.sh pnpm build

# Build a single HTML from the bundled examples
scripts/app.sh node packages/cli/dist/index.js build examples/en -o dist/docs.html

Next steps

• See Command Options for the CLI reference (init / build / watch / serve / validate).
• See Configuration for the monodocs.config.yml options.
• See the roadmap for the version plan.
• See supported syntax for what is supported and what single-file bundling intentionally restricts.