md-press

Press Markdown into clean pages. Pure code: no AI, no tokens, no build setup.

npm install -g @sirux/md-press
md-press notes.md           # build notes.html, a page you can share anywhere
md-press serve notes.md     # open notes.md live, checkboxes save into the file
md-press board backlog.md   # open backlog.md as a Kanban board that writes back to it

Why

Notes, plans, and trackers live best as Markdown. They read best as a page, and a backlog works best as a board. md-press gives the file a better view without taking it away from you. The file stays the source of truth, readable and editable by people, editors, and agents alike.

Three ways to use it

Build: a page to share

md-press notes.md                   # writes notes.html next to notes.md
md-press docs --out pages           # builds every .md in docs/, keeping its folders
md-press - < notes.md > notes.html  # reads standard input, writes standard output
npx @sirux/md-press notes.md        # runs without installing

You get one HTML file with its styles, scripts, and images inlined, ready to open, send, print, or host anywhere. Links to other .md files point at the pages they become. Checklist progress on a built page is saved in the viewer's browser.

Serve: a live page for working

md-press serve notes.md

Opens notes.md at http://localhost:5180.

• Checking a box saves [x] into the file. Only that one character changes.
• Edit the file anywhere, in an editor or with an agent, and the page updates on its own, keeping your scroll position.
• Safe with other editors. If the file changed since the page loaded, a save is refused and the page reloads, so no one's edit is overwritten.
• Images next to the file show up, so relative links like ![](screenshot.png) work.

Stop it with Ctrl+C.

Board: a live Kanban board

md-press board backlog.md

Opens backlog.md as a board at http://localhost:5180. Nothing about the file has to change to make it one:

# Launch backlog

## Todo
- [ ] Write the announcement `docs`
- [ ] Fix the login redirect `bug` `p1`
  - happens only with single sign-on

## Doing
- [ ] Ship 0.2 `release`

## Done
- [x] Set up CI `ops`

• ## headings are columns. The - [ ] items directly under one are its cards. Indented lines under a card are its notes and move with it.
• Trailing `code` spans are tags. They get a color from their name. Click a tag at the top to filter the board.
• Drag a card to another column or position, or pick a column from the arrow menu on the card. Only the card's own lines move in the file. Move it back and the file is byte for byte what it was.
• The last column counts as done. A card moved into it is checked, a card moved out is unchecked. Tick a card's box to check it where it is. A board with a single column has no done column.
• Add a card by typing at the bottom of a column. It becomes a - [ ] line there.
• Same server, same rules as serve. The board reloads when the file changes, a stale save is refused, and writes are atomic. /page shows the reading view of the same file, and md-press serve has /board.

Try it on examples/backlog.md.

Options

Option	Mode	What it does
--out <folder>	build	Writes pages into this folder instead of next to each file. A folder given as input keeps its structure
--port <number>	serve, board	Port to start from. Default 5180, and the next 9 are tried if it is busy
--no-open	serve, board	Does not open the browser
-v, --version	any	Shows the version
-h, --help	any	Shows help

md-press build notes.md works too, same as md-press notes.md.

What every page gets

• Light and dark mode that follow the system setting, plus clean print styles.
• Readable on phones. Wide tables and code scroll inside themselves, long links and words wrap, and the page itself never scrolls sideways.
• Code highlighting, done when the page is made, so pages stay fast. Every block has a Copy button.
• Checklists. - [ ] items become real checkboxes with a progress bar.
• Anchor links. Every heading gets a GitHub-style id, so [see below](#install) and hand-written tables of contents work.
• Callouts. > [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION] render the way GitHub shows them.
• Footnotes. [^1] in the text, [^1]: The note anywhere in the file.
• Table alignment from :---: and ---:.
• Smart titles. Uses frontmatter title:, then the first # heading (underlined headings count too), then the first heading of any level, then the file name. A # inside a code block is never a title.
• Diagrams. ```mermaid blocks render as diagrams. This is the only feature that loads anything from the network, and only on pages that have a diagram. Offline, the diagram source shows instead.

See examples/showcase.md for every feature on one page. Try it both ways.

Frontmatter

---
title: Q4 launch plan
description: Owners, dates, and open risks
lang: th
---

title sets the browser tab title. description sets the page's meta description. lang sets the page language, which browsers use for line breaking and fonts; the default is en. Other keys are ignored for now.

Use it from code

const { renderPage, buildFile, parseBoard, moveCard, addCard } = require("@sirux/md-press");

const html = renderPage("# Hello\n\n- [ ] Ship it", "hello.md");
buildFile("notes.md", "pages");

const board = parseBoard(backlogText);                              // { title, columns: [{ title, cards }] }
const moved = moveCard(backlogText, { column: 0, index: 1 }, { column: 2, index: 0 });
const added = addCard(backlogText, 0, "Write the announcement `docs`");

renderDocument returns the page with its title and task counts. moveCard and addCard return the new file text and change nothing but the lines involved.

Good to know

• Built pages save progress per browser, keyed by file name. Only serve and board write to the file.
• Images are inlined up to 4 MB each. Bigger or missing ones stay as links, and the build says so.
• A served page is read-only if md-press cannot match every checkbox to its line, for example when a task sits inside an indented code block. It says so in the toolbar, and the terminal says how many task lines and checkboxes it found.
• On a board, only top-level - [ ] items under ## headings are cards. Tasks before the first ## heading and nested tasks show on the page but not on the board.
• Raw HTML is kept, so <kbd> and <details> work. To show a tag as text, wrap it in backticks. Only press or serve files you trust, the same as opening any HTML file.
• serve and board answer only this computer. They are not reachable from your phone or network.
• The package is @sirux/md-press, the command is md-press. npm reserves plain md-press because it is close to an older, unrelated package.
• Requires Node 20 or newer.

Docs

• How it works
• Decisions
• Roadmap
• Contributing
• Security
• Changelog

License

MIT © Sirasit Thitirattanakorn. Made by Sirux.