Download this page as .mdz

How these pages are made

Most pages on this site, including every docs page and news post, are each one .mdz file: the text and its images, packaged together. The rest are the home page and a few other hand-built pages, the in-browser tools, the specification (plain Markdown from its own repository) and lists the build makes, like the sitemap. This page shows how the .mdz pages are written and published. It describes this site's own setup, not a tool you can download: the build that turns the files into a website is written for this site alone.

flowchart LR
    A["`✏️ **Write**
in Studio or VS Code`"]
    A --> B["`💾 **Save**
one file per page`"]
    B --> P2["`👀 **Preview**
a local copy of the site`"]
    P2 --> C["`🚀 **Publish**
push the change to GitHub`"]
    C --> C2["`**The live site updates**
each page built to HTML`"]
    B --> D["`📄 **Share the file**
if you like`"]
    D --> D2["`**Opens anywhere**
Studio, VS Code
or the web editor`"]

    classDef you stroke-width:2px;
    classDef auto fill:none,stroke-width:1.5px,stroke-dasharray:5 4;
    class A,B,C,D you;
    class P2,C2,D2 auto;

Solid boxes are what the author does. Dashed boxes happen on their own.

Write

Pages are edited like any other .mdz: in MDZip Studio or the VS Code extension, with images pasted or dropped right where they belong. AI agents working on the site use the mdz command line (more on how MDZip is built). There's no separate media library: an image used on a page is stored in that page's file.

Save

Each page saves as one .mdz, an ordinary ZIP of Markdown and images. Because the images are inside the file, they stay with the page when it's moved, renamed, emailed or backed up, the way pictures stay inside a Word document.

Preview, then publish

Saving doesn't change the live site. A local copy of the whole site rebuilds whenever a page is saved, so every page can be checked exactly as visitors will see it before it goes out.

Publishing is a separate step. Today that means committing the change and pushing it to GitHub, where the site's build runs: it unpacks each .mdz and turns it into a plain HTML page that loads fast and that search engines can read in full. Images are placed automatically, and an image used on two pages is published only once.

Committing and pushing are developer steps, and they're the part a non-developer would get stuck on. The goal is for "save" and "publish" to be the only steps an author needs. Until then, publishing this site takes a developer.

Each of these pages is also a file

Each page made from an .mdz ends with a note to download it, and that download is the page's source file, not an export. Open it in MDZip Studio, the VS Code extension or the web editor and you're holding the same page, images included. Rename .mdz to .zip and extract it, and you have plain Markdown and images any tool can read. Each file also carries a short README.md saying what it is and how to open it, and an AGENTS.md with the same for AI tools, as the specification recommends.

Can I build my site this way?

Not with a ready-made tool, at least not yet. The build is written for this site and isn't packaged for anyone else to use.

It could be the start of one, though: a CMS-like workflow where each page is a file you write in an ordinary editor, with no database and no media library, and publishing turns the files into a fast static site. Today the pieces underneath it are available: the core libraries read and write .mdz files, and the editor component shows them in a browser. If a tool like that would be useful to you, say so in Ideas.

About the diagram

The flowchart at the top isn't an image. It's a Mermaid code block inside the page, drawn by your browser here, and again when you open the downloaded .mdz in Studio, VS Code or the web editor.

This page renders from authoring-flow.mdz (MDZip, ~4 KB, updated 2026-11-10) — one self-contained file. Download it, open it in the web editor, or read how these pages are made.