How it works
Understand the architecture behind Blode.md's docs-as-code platform.
Blode.md turns local MDX files into a hosted documentation site. Here is how the pieces fit together.
Your repo CLI API CDN + Renderer
───────── ───────── ───────── ───────────────
docs/ ───► blodemd ───► Hono API ───► Next.js app
├ docs.json push ├ validate ├ tenant routing
├ index.mdx ├ store in ├ MDX rendering
└ *.mdx │ Vercel Blob ├ Shiki highlighting
└ build indices └ edge caching
The CLI reads docs.json and validates it against the configuration schema.
If the config is invalid, the push stops with an error.
All files in your docs directory are collected. Dotfiles and node_modules
are skipped.
The CLI creates a new deployment record via the API. If the project does not exist yet, you are prompted to create it.
Files are uploaded in batches (up to 4 MB per batch) and stored in Vercel Blob storage.
The API builds search indices, compiles MDX to optimized JSON, generates a deployment manifest, and promotes the deployment to live.
When a reader visits your docs site, the renderer:
Each project is an isolated tenant. Tenants are identified by subdomain (project.blode.md), custom domain, or path prefix. Tenant configuration, content, and deployments are fully isolated from each other.
During finalization, the API generates several indices alongside your content:
robots.txt, sitemap.xml, and llms.txt