local Markdown docs, offline Mermaid, mdBook today

mdview

A small local Markdown viewer that discovers related docs, generates an mdBook workspace, embeds Mermaid support, and opens the rendered page from `.cache/mdview`.

Repository Project Outlook

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 Preview

`mdview SomeDoc.md` prints the file to your terminal; `mdview book open SomeDoc.md` builds the whole-project documentation book and opens the generated HTML from `.cache/mdview`.

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 is currently a doc manager for mdBook. It prepares a temporary book workspace and lets mdBook do the final HTML rendering.

1. Input`SomeDoc.md`

2. Discoverroot and related docs

3. Summarizefrontmatter to `SUMMARY.md`

4. Build`mdbook build .cache/mdview`

5. Opengenerated local HTML

local shell 127.0.0.1 optional

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

$ mdview book build AGENTS.md
$ mdview docs/Project.md

Where This Is Going

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.
Show images in terminal views through codeberg.org/ubunatic/cati.
Keep local-first behavior, offline operation, and small memory use as design constraints.