mdz — any web page to LLM-ready Markdown

Turn a web page into markdown that an LLM can read. One binary. No account. No API key. Nothing leaves your machine.

Quick start

# one page to markdown on stdout
mdz https://example.com/post

# write it to a file, with a JSON manifest next to it
mdz https://example.com/post --out post.md --json-out post.json

# one .md per section, plus index.json
mdz https://example.com/post --split out

# a whole docs section, two levels deep
mdz https://example.com/docs --crawl 2 --split out

mdz --help lists every flag. mdz --version prints the version.

Related MCP server: codearia-sieve

Install

Download one file and make it executable. Pick your platform.

# Linux x64
curl -fsSL https://github.com/pahlevikun/mdz/releases/latest/download/mdz-linux-x64 -o mdz && chmod +x mdz

# macOS, Apple Silicon
curl -fsSL https://github.com/pahlevikun/mdz/releases/latest/download/mdz-darwin-arm64 -o mdz && chmod +x mdz

# macOS, Intel
curl -fsSL https://github.com/pahlevikun/mdz/releases/latest/download/mdz-darwin-x64 -o mdz && chmod +x mdz

# Windows x64
curl -fsSL https://github.com/pahlevikun/mdz/releases/latest/download/mdz-windows-x64.exe -o mdz.exe

Then move it onto your PATH:

sudo mv mdz /usr/local/bin/      # Linux and macOS

Not on npm. Build from source with bun run build:cli.

Verify the install:

mdz --version
mdz https://example.com | head -20

What you get

---
title: Example Domain
url: https://example.com/
domain: example.com
lang: en
words: 25
chars: 156
tokens_o200k: 28
tokens_cl100k: 28
chunks: 1
extractor: defuddle
generator: mdz
---

This domain is for use in documentation examples...

• Markdown split by heading. Each section becomes a chunk with a stable id like 01-install.

• Token counts from the real tokenizer, for both o200k and cl100k. Not length / 4.

• YAML frontmatter that Obsidian and Logseq read without changes.

• The same extraction in three places: CLI, MCP server, browser extension.

Use it as an agent tool

mdz-mcp speaks MCP over stdio. An agent can read a 40k-token docs page two sections at a time instead of swallowing it whole.

Client config:

{
  "mcpServers": {
    "mdz": {
      "command": "mdz-mcp"
    }
  }
}

The skill that makes it work

Tools alone do not make an agent read in the right order. skills/mdz-read/ does: outline first, then only the chunks the question needs, plus what to do when a page is blocked or JS-only.

npx skills add pahlevikun/mdz/skills/mdz-read

The repo also ships AGENTS.md, which holds the short form of the same rules for agents that read a repo root instead of installing skills.

Two limits the tools report themselves rather than hiding:

• mdz fetches over HTTP and does not run JavaScript. A page that renders its body client-side comes back empty, and tokens: 0 says so.

• mdz_design_tokens samples declared CSS, not rendered pixels. A page styled only by external stylesheets returns few colors.

Browser extension

Chrome and Firefox, Manifest V3. Install from the release zip, or load apps/extension/build/chrome-mv3-prod unpacked.

The preview tab is an editable markdown pane beside a live render, with a chunk picker, a token badge, copy, download, and export.

Also in the preview tab:

• Full page screenshot — scrolls and stitches the whole page into one PNG.

• Copy for Figma — puts HTML, PNG and markdown on the clipboard together. Paste into Figma desktop and you get editable frames, not a flat image.

• Design tokens — downloads DESIGN.md and tokens.json built from the page's own palette.

• Stack — lists frameworks, analytics and hosting found in the page, with the evidence for each finding.

Dark and light simulation per tab. Approximate by default, using a CSS filter. Grant the optional debugger permission in settings to get the site's real theme instead.

Permissions

activeTab, scripting, contextMenus, storage, clipboardWrite.

Optional: debugger, only if you turn on precise theme emulation.

There is no host_permissions and no content script. The extension reads the active tab when you press a shortcut, and never before.

Design

The palette, type scale and component rules live in DESIGN.md. Machine-readable copies are in design/, and bun run scripts/check-tokens.ts fails if the files drift apart.

Development

bun install
bun test
bunx tsc -b
bun run build:cli
bun run build:mcp
cd apps/extension && bun run build --target=chrome-mv3

Gates that must stay green:

bun test                        # 119 tests
bunx tsc -b                     # types
bun run scripts/check-tokens.ts # DESIGN.md, tokens.json, tailwind agree
./scripts/check-hygiene.sh      # no other-tool names in the tree

License

MIT. See LICENSE.