Markdown versus K2F
Markdown is the easiest format for agents to write. K2F is a compiled document: a semantic tree plus a geometry lock. You can move text between them. You cannot pretend they are the same file.
K2F is not a lossless superset of Markdown. Round-trip is supported and lossy.
At a glance
| Topic | Markdown | K2F |
|---|---|---|
| What the file is | Plain text with lightweight markup | Semantic tree + geometry lock in a ZIP |
| Pixel-stable pages | No | Yes — viewers paint document.K2F.lock |
| Agent-stable node ids | No | Yes — dotted ids in the semantic tree |
| Semantic roles vs presentation | Headings / lists | Roles + Theme |
| Integrity banner | No | Required |
| Markdown round-trip | Native | Supported and lossy for theme, lock, and node ids |
What Markdown is good at
Markdown is the right choice for notes, READMEs, and agent scratchpads. Headings and lists are cheap. Diffs are readable. Every model already speaks it.
This site’s Markdown mirrors (/compare/index.md, /spec/index.md) exist so agents can fetch token-light GFM. That is documentation, not a .K2F package.
What K2F adds
A .K2F package stores meaning as JSON nodes with dotted ids, then compiles exact geometry. Viewers paint the lock. Markdown has no lock, no integrity banner, and no stable ids across a rewrite.
The K2F skill still starts from Markdown-shaped intent — then the engine compiles a package. The skill is a writer’s on-ramp, not a claim that Markdown is K2F.
Honest losses versus Markdown
- Round-trip drops theme, lock, and node ids. Export Markdown to share prose; do not expect the same package back.
- No pixel stability. Renderer differences (GitHub, VS Code, this site) are normal for Markdown and unacceptable for a K2F lock.
- No integrity banner. A
.mdfile cannot be SIGNED in the K2F sense.
When to pick which
- Stay on Markdown for drafts, docs, and anything that should remain a text file.
- Use K2F when the published artifact must be a page with a lock and agent-editable ids.
- Use Markdown as input, then compile — do not ship the
.mdas the customer’s document.
See converting Markdown and the Compare matrix.