From Markdown Files to a Local Viewer

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 you just want to inspect one page. mdview tackles that small, common gap with a Go command line tool that can render one Markdown file in a terminal or HTML, or build a navigable local book from a project’s Markdown.

The book workflow discovers Markdown below a project root, uses optional title, parent, and weight frontmatter to build navigation, and prepares an mdBook workspace under .cache/mdview. Mermaid support is self-contained: the browser-side JavaScript is embedded in the binary, so rendering a diagram does not depend on a CDN. The standalone --html mode takes another route, producing one page for one file and copying its local images beside it. The terminal renderer handles common Markdown constructs and can draw local PNG, JPEG, and SVG images through the sibling cati library.

One useful engineering episode came from SVG sizing. A rasterizer may decode an SVG into a convenient pixel buffer whose dimensions do not match the size the author declared in the SVG. If the terminal renderer treats those raster bounds as the intended display size, a small icon can occupy far too many terminal cells. The July 1 change f127b43 specifically scales SVG images by their declared size rather than cati’s rasterization bounds. The repository also includes tests for SVG sizing, missing dimensions, image scaling, debugging decisions, and placeholder behavior. This is a small example of a good boundary between components: cati performs image rendering, while mdview applies the Markdown and terminal display rules.

The project’s agentic development evidence is modest but visible. The history contains 17 commits, with its initial book workflow, website, and terminal renderer arriving in a concentrated sequence on July 1, 2026. A July 2 refactor separated the print and book commands. Two later commits, on August 29 and September 5, synchronize the repository’s Harnez-managed development guides; their commit records include Claude co-author metadata. The local guides describe a five-phase loop, issue-file tracking, advisor escalation, and feedback recording. That documents the workflow expected in this repo, but the visible history does not establish that advisors, reverse-sprints, or multi-agent work were used to implement mdview. It would be misleading to claim that this small codebase could not have been built by one developer. The more grounded takeaway is that an agent-assisted workflow can leave reviewable artifacts: commits, tests, issue files, and repeatable conventions.

The code remains intentionally compact. Its two renderers use lightweight regular-expression handling rather than a large Markdown framework, and unrecognized terminal constructs pass through as text. The tradeoff is visible in the open issue list: it records known gaps such as hiding frontmatter in terminal output and copying referenced images into generated books. The backlog also distinguishes shipped terminal image rendering from future ambitions such as an interactive document browser and terminal Mermaid diagrams. Keeping these edges explicit gives future work a concrete starting point.

For a visitor, the practical promise is straightforward: start with a local Markdown file, choose a terminal preview, one-file HTML page, or project book, and keep the result on your machine. The project is small enough to inspect, but already joins document discovery, navigation, browser rendering, terminal output, and image handling into one tool.

Facts