Pitch deck
The hackathon pitch, in the medium it is arguing for. Everything below is a slide; the deck itself is the same content in a room.
Our docs can't keep up with our product
Today. Written by hand, published through a slow CMS, updated whenever somebody remembers — while the product it describes changes every day. Agents read stale pages and integrate SEON wrong.
Where we want to be. Every page plain Markdown, held in git. Updates generated from what actually shipped. Reviewed and published in minutes rather than weeks. Readable by the agents doing the integrating.
So we rebuilt it
SEON's documentation as Markdown in git — live, on real content, at hackathon.seondf.net. The site you are reading is the thing being pitched.
Why Markdown-based docs
The format decides who — and what — can actually read our documentation.
Readable by agents. LLMs and coding agents read our docs before any engineer does. Every page is served as raw Markdown at a predictable URL, with llms.txt indexes for discovery.
Faster to edit. Anyone who can write Markdown can fix a page and open a pull request. No CMS queue, no publish cycle to wait on.
Versioned by default. Every page lives in git — full history, diffs and rollback across API reference, SDK guides and knowledge base alike.
What our docs cost an agent today
Measured across four live docs.seon.io pages:
| 24× | Fewer tokens to read the same page as Markdown instead of as served HTML |
| 141k | Tokens an agent burns fetching a single knowledge-base page today |
| 49% | Of that page is a JSON copy of content the agent already has |
The page-by-page figures and the method are on Measurements.
What we serve to agents
Built and merged — 4,551 tokens for the page that costs 60,281 today.
Markdown at two URLs. Every page published as raw Markdown at both /page.md and /page/index.md, with content negotiation on an Accept header for agents holding the canonical link.
llms.txt, three tiers. A root index of every page, a per-section index for pulling one product without the rest, and llms-full.txt carrying the whole corpus for bulk ingestion.
Current, not just public. Deprecated pages still render and still resolve, but drop out of every index and crawl — so an agent is never led to a path we no longer recommend.
Full detail in Reading these docs as an agent.
Stripe already solved this
Markdoc powers docs.stripe.com, and they open-sourced it.
Proven at scale. Stripe built Markdoc for what they call their largest and most complex content site, then adopted it company-wide — thousands of pages, hundreds of thousands of lines of Markdoc.
Free to run. MIT licensed and open source. No per-seat or per-project licence fee, which is exactly what the commercial documentation platforms charge for.
A benchmark we already use. docs.stripe.com is the internal reference for what good documentation looks like. Adopting the framework behind it makes that target concrete rather than aspirational.
We control the whole stack
No CMS in the critical path, and no vendor deciding what our documentation is allowed to do.
- Fast by default — static Markdown, no CMS round-trip on every page load
- No lock-in — MIT licence, and the content is plain files we own outright
- Built to fit — custom tags for exactly the components our docs need
Docs get the workflow code already has
None of this has to be built — it is what git and pull requests already do.
Reviewed before it ships. Every change is a pull request: someone reads the diff, and the whole site builds locally to check the rendered page. Production only moves when a person merges.
History and rollback. Who changed a page, when and why; the diff between any two points; a one-command revert. A cleaner audit trail than a CMS revision log.
Anyone can write. The CMS existed so non-engineers could publish. AI coding assistants have largely removed that barrier — a visual editor becomes optional rather than a prerequisite.
Docs become a build output
Every docs page in Markdown — proved on IDV first.
A — the platform. Export docs.seon.io content out of Strapi into Markdown; API reference, SDK guides and knowledge base alike; rendered with Markdoc, held in git so versioning is free; raw Markdown at predictable URLs for agents.
B — the pipeline. Triggered on release; filters for anything a customer can observe; applies each repo's rules for what is public and what is current; opens a pull request — it proposes, never publishes.
How this documentation is generated walks a release through it end to end.
The more we publish, the better SEON integrates
Documentation coverage is quietly becoming an integration-quality metric.
- More content — automation makes detail cheap to produce and cheap to keep current
- Better agent grounding — agents integrating SEON read complete, current pages
- Fewer wrong integrations — support load and SE time fall as the docs stop lagging