Shipping a small MDX site without inventing a content platform
A few practical reasons to keep a personal-site content system explicit: local files, typed metadata, and minimal abstractions that match the real scope of the project.
One of the easiest mistakes in a personal site is solving the wrong scale of problem. It is tempting to add content discovery, frontmatter parsing, schema validation, and a few layers of helper code before there is enough content to justify them.
For a small site, a local MDX workflow often gets you most of the benefit with much less operational weight:
- content lives next to the app
- routing stays obvious
- version control shows both copy and code changes together
- the rendering surface is constrained enough to stay readable
Where the explicit approach helps
The main win is not that the system is simpler in the abstract. The win is that another engineer can understand it quickly.
In practice, that means:
- metadata lives in the file that owns the content
- the blog registry is explicit rather than inferred
- shared MDX components stay small and stylistic
- route generation is tied directly to the registered posts
That tradeoff is often correct until one of two things changes: the volume of content increases significantly, or non-engineers need a different authoring workflow.
What I optimize for first
When I build a content-heavy surface, I usually prioritize the same things:
- clear ownership of data and rendering
- predictable routing and page generation
- enough reuse to avoid duplication, but not so much indirection that maintenance slows down
This is the sort of system that starts small, stays understandable, and still leaves room to evolve later if the requirements change.