For a developer portfolio, the content layer should serve two goals: easy to edit for the developer, and easy to extend when requirements grow. A hosted CMS is great for teams; for a solo developer writing occasional technical articles, it's overkill — another account, another API, another thing that can go down.
The setup
Each article is a Markdown file with YAML frontmatter, one per language, living in the repo under content/blog/:
content/blog/
my-article.en.mdx
my-article.es.mdx
The frontmatter carries the metadata — title, excerpt, date, tags — and the body is plain Markdown. A small build script reads the frontmatter from every file and writes a metadata index that the article list, the sitemap and the project cards consume. The article bodies are read straight from disk at build time and rendered as static pages.
Why MDX and not plain Markdown
Ninety percent of an article is prose, headings, code blocks and the odd image — all standard Markdown. But every so often a topic needs a diagram you can actually interact with: a plot that responds to a slider, a small proof you can step through. MDX lets me drop a React component into the middle of the prose for exactly those moments, without turning the whole pipeline into an app.
Standard Markdown handles the 90%.
A React component handles the 10% that needs to move.
When a CMS earns its place
- Multiple non-technical authors who won't touch Git
- A publishing workflow with drafts, scheduling and review
- Content reused across several surfaces (web, email, mobile)
None of those apply to one person writing a handful of posts a year.
Start with the simplest content layer that solves the problem. You can always migrate to a CMS when the writing outgrows a folder of files.