Adopt Git-backed MDX with strict Zod validation
- mdx
- zod
- static-export
Context
The Engineering Command Center needs a durable, reviewable content layer for ADRs, journals, blog posts, projects, and certifications. Runtime databases are out of scope for V1 (static export on Cloudflare Pages), and content must be versioned alongside the code that renders it.
Decision
Store all content as MDX files under /content with YAML frontmatter validated by strict Zod schemas at build time. Invalid or missing fields fail the static export with an explicit error naming the file and field.
Consequences — Positive
- Content is Git-backed and reviewable through the normal PR flow
- Build-time validation catches typos and missing fields before deploy
- No database or runtime server is required in V1
Consequences — Negative
- Schema changes require a migration of every content file
- Large binary assets still need a separate strategy
The parser
Every route on swbanga.com that renders long-form content — ADRs, engineering journals, case studies — needs a single ingestion path. The architecture invariant is strict static export, so the parser must run during the build.
Adopt next-mdx-remote for MDX compilation and zod for frontmatter
validation. The parser lives in src/lib/mdx.ts:
const parsed = CONTENT_SCHEMAS[contentType].safeParse(file.data);
if (!parsed.success) {
throw new Error(
`Invalid frontmatter in ${filePath}:\n${formatZodIssues(parsed.error)}`,
);
}
Enforcement
The build becomes the enforcement point: a missing summary or a mistyped
publishedat aborts the export before it reaches Cloudflare.