md-aio: read a whole folder of Markdown as one document · Gor Berlian · diadem.fun
← Gor Berlian
ReportNov 18, 20263 min read

md-aio: read a whole folder of Markdown as one document

Contents

md-aio is a small local viewer for Markdown. Point it at a file or a folder and it opens a window that shows everything as one continuous document, laid out in newspaper-style columns about 80 characters wide. It was built for reading what AI agents write: long reports, plans and notes that change while you read them.

What it does#

  • One document from many files. A folder's Markdown files are joined in order, each under its own file name.
  • Columns, not scrolling. As many 80-character columns as fit the window; you page through them with the keyboard or the mouse wheel.
  • Live reload. When a file changes on disk, the window updates in place and keeps your position.
  • Math, tables and code. Formulas are rendered with KaTeX; tables and fenced code blocks look the way they should.
  • Nothing from the internet. Every library and font is bundled, so a document can't make the viewer load remote code.

New this week#

Outline#

Press o for a sidebar listing the headings of every file. Click a heading to jump to it; the heading you are reading is marked.

The outline sidebar listing the headings of two files

Search across the folder#

Press / and type. Every match in every file is highlighted and counted; Enter, then n and N move between matches, Esc clears.

Search for a word: three matches highlighted across two files

What changed#

When a file is rewritten while the window is open, the blocks that changed get a blue bar for a minute. Press c for a list of the last 20 changes, each under the heading it belongs to.

Recently changed list and two changed paragraphs marked with a blue bar

The renderer as a module#

The part that turns Markdown into HTML is now a module of its own, md-aio/render. A website can use it on the server to publish the same documents, with a stylesheet for phones and desktops, and the viewer uses the same module, so the two always agree.

How it is tested#

Check Result
Unit tests for the outline, search matching and change detection 12 pass
Unit tests for the renderer: headings, tables, math, link rewriting, and input that tries to inject scripts 10 pass
The real page in a headless browser: open a folder, open the outline, search, rewrite a file All three features respond, no page errors
A long document with the outline open Still two full columns, paging works

The browser check is a script that drives a real Chrome over its debugging port, presses the keys, rewrites a file on disk and reads back what the page shows. The screenshots above come from that run.

Security#

md-aio listens only on the local machine. Each window carries a signed address, so one window can't be used to read another folder. Raw HTML inside Markdown is not rendered, and files other than images are offered as downloads, never run.

What is next#

  • Footnotes, callouts, highlighted code and figure captions in the renderer.
  • Packaging, so a website can install the renderer instead of copying it.
Gor Berlian

One person, many companies, one coin. Every project I build sends a share of its revenue back to buy $BERLIAN on the open market, and every buy is published with its transaction.

See the page

More from Gor Berlian