MinkNote's Documentation Is Written in MinkNote

The MinkNote documentation on this site — 19 pages, 8 sections, screenshots and all — isn’t maintained here. It lives in a MinkNote journal on my Mac, and I’ve never hand-edited a single generated page.

The problem with writing docs twice

Writing docs is unpleasant enough. Writing them somewhere pleasant and then porting them somewhere publishable is worse, and it’s the reason docs go stale: the friction isn’t the writing, it’s the publishing. Every small correction means opening a second toolchain, matching whatever front matter the site expects, re-uploading images, fixing links, updating the sidebar.

So I stopped doing the second part.

One skill, one command

I wrote an agent skill — minknote-docs-import — that treats the journal as the single source of truth and regenerates the site’s docs section from it. It reads every note in the journal and:

• maps folders to sidebar sections (Editing and Formatting/ becomes a section, notes at the root become Getting Started)
• writes the Jekyll front matter each page needs, including a stable permalink
• rewrites minknote:// note links into real web URLs, so internal cross-references survive the trip
• copies the images across and repoints them
• turns YouTube shortcodes into embeds
• regenerates the sidebar navigation file

Anything I don’t want published — the changelog, the roadmap — gets passed as an ignore pattern and stays private.

Here’s what an update actually looks like. I fixed some wording, added a new page on free and pro access, and asked for a re-import:

Sixteen seconds. Nineteen pages rebuilt, one new page slotted into the right sidebar section with the right URL, and a diff I can read before anything goes live.

Why this is the right shape

The generated pages are disposable. The import mode deletes what it made last time and rebuilds from scratch, which sounds destructive but is exactly what makes it safe — there’s no drift to reconcile, no half-migrated state, no temptation to make “just one quick fix” in the published copy that gets blown away later. If the output is wrong, the input is wrong, and there’s only one place to go fix it.

It also means the docs get whatever MinkNote is good at: fast search across the journal while I’m writing, linked notes that stay linked once published, images pasted in without ceremony.

Try it

The skill is on GitHub at demianturner/minknote-skills. It’s not MinkNote-specific in any deep way — if you keep Markdown notes in folders with an image directory alongside, it’ll probably work for you with a couple of flag changes.

And the output is right here: MinkNote docs.