Local Markdown · Offline Mermaid · mdBook

mdview read connected Markdown documents locally.

Render a Markdown file in your terminal or as standalone HTML, or build a navigable mdBook from related project documents. Generated navigation and embedded Mermaid keep the book useful offline.

go install ubunatic.com/mdview@latest

Explore the workflow View source

Project snapshot · measured 2026-10-26

Key facts

Commits 21Last commit 2026-10-06 Source receipt ↗ Commits · 7 days 0 Source receipt ↗ Tickets closed 1 / 1 Source receipt ↗ Studies 1 Source receipt ↗

12-week commit activity

2026-10-26

Aug 3

Aug 10

Aug 17

Aug 24

Aug 31

Sep 7

Sep 14

Sep 21

Sep 28

Oct 5

Oct 12

Oct 19

View 12-week data table

Week starting	Commits
2026-08-03	1
2026-08-10	0
2026-08-17	0
2026-08-24	1
2026-08-31	1
2026-09-07	0
2026-09-14	0
2026-09-21	0
2026-09-28	0
2026-10-05	1
2026-10-12	0
2026-10-19	0

Key Features

Renders one Markdown file in the terminal or as a standalone HTML page.
Builds navigable mdBook sites with offline Mermaid text-to-diagram support.

Stack

Go 1.25, Cobra, cati, mdBook, embedded Mermaid JavaScript

Why mdview

Read project docs without assembling a book by hand

Project documentation is spread across related Markdown files. mdview discovers them from one input file, organizes their frontmatter into a table of contents, and delegates multi-page HTML rendering to mdBook. Single-file terminal and HTML previews keep small reading tasks simple.

Workflow preview

From Markdown to a local documentation book

mdview workflow illustration from local Markdown discovery to a navigable documentation book — The original mdview workflow illustration.

What mdview Offers Now

The current project scope is intentionally narrow: manage local Markdown docs as an mdBook, with generated navigation and offline Mermaid rendering.

Doc Discovery

Starts from one Markdown file, finds a project root, and gathers related docs while skipping cache and dependency directories.

Generated mdBook

Creates book.toml, SUMMARY.md, and a mirrored source tree under .cache/mdview, then runs mdbook build.

Offline Mermaid

Embeds local Mermaid JavaScript assets into the generated book so diagrams work without CDN access.

Frontmatter Hierarchy

Uses title, parent, and weight frontmatter to shape the mdBook summary and automate ToC creation.

Local & HTML Preview

mdview SomeDoc.md renders Markdown and inline images directly in your terminal; --html produces a standalone single-file preview, and mdview book open builds the full mdBook.

Small Go CLI

The implementation stays compact, avoids Electron and TypeScript, and uses external tools only where they already fit the job.

How It Works

mdview renders single files to the terminal or standalone HTML, or prepares a project workspace and lets mdBook do the final multi-page HTML rendering.

Input a Markdown file such as SomeDoc.md.
Discover the project root and related documents.
Summarize frontmatter into SUMMARY.md.
Build with mdbook build .cache/mdview.
Open the generated local HTML.

mdview docs/Project.md
mdview docs/Project.md --html
mdview book open docs/Project.md

Terminal output includes ANSI text and cati images. --html produces a standalone single-file preview; book open builds the whole-project mdBook under .cache/mdview/book. Serving a local book uses 127.0.0.1.

A sample whole-project book run reports its discovered pages and local output:

root /home/uwe/projects/mdview
pages 5
built .cache/mdview/book
opened .cache/mdview/book/docs/Project.html

Where This Is Going

These directions are planned work, not claims about current features.

The long-term direction is broader than mdBook: mdview should become a Markdown docs browser that feels like cat plus tree, but interactive and built for connected documentation.

Like cat and tree, but for Markdown projects.

Support other Markdown browser/render targets beyond mdBook.
Provide an interactive terminal docs browser with fast tree navigation.
Render Mermaid in the terminal with smart ASCII or Unicode art output.
Keep local-first behavior, offline operation, and small memory use as design constraints.

Project details

Stack

Go 1.25, Cobra, cati, mdBook, embedded Mermaid JavaScript

Source

https://codeberg.org/ubunatic/mdview ↗

Architecture

Layer composition

Terminal: ANSI rendering
Desktop: —
Inference / AI: —
Containers / VM: —
Web: standalone HTML, mdBook

Engineering story

mdview: the story behind the project

Most software projects already have useful documentation. The friction is getting from a file in a checkout to a readable view: a browser-based book needs navigation, diagrams should work offline, and opening a full browser is overkill when…

Read the engineering story

Measurement source · 2026-10-26

Verification receipts

Commits: 21 · Last commit 2026-10-06
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Commits · 7 days: 0
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Tickets closed: 1 / 1
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Studies: 1
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
12-week commit activity
git rev-list --count --since=<Monday> --until=<Sunday> HEAD
12 latest complete ISO weeks; weekly values are from spec/metrics.yaml.