Small content sites do not always need a CMS

A CMS is often treated as a standard item on the website checklist. Sometimes it is exactly the right choice. Other times, it adds an admin interface, database, credentials, and maintenance workflow to a site maintained by one technical person a few times a month.

For a portfolio, documentation site, or small publication, local Markdown can be a more comfortable place to start.

The file can be the interface

This site keeps projects and articles in MDX files. Each file contains a short frontmatter block and the body of the page. The filename becomes the URL, Git records every change, and the content travels with the application.

That workflow would be a poor fit for a nontechnical editorial team. For a developer maintaining a personal site, it is direct. There is no second system to log into and no question about whether code and content are out of sync.

Treat content like data

Local files should not mean unstructured files. Titles, summaries, dates, tags, draft status, and cover images can be checked during the build.

const postSchema = z.object({
  title: z.string().min(1),
  publishedAt: z.string().date(),
  draft: z.boolean().default(false),
});

The important part is not Zod specifically. It is having one explicit contract. A missing title or malformed date should fail while I am working, not quietly create a broken card in production.

Keep the route predictable

Deriving slugs from filenames creates an obvious relationship:

content/blog/designing-better-forms.mdx
→ /blog/designing-better-forms

That predictability makes the system easy to inspect. Static generation can then build the article pages ahead of time, which keeps delivery fast and avoids runtime content infrastructure.

Do not romanticise simplicity

Markdown has edges. Image management is manual. Previewing a draft takes a local or preview build. Scheduling, permissions, and multi-author review are not built in.

Those are not tiny inconveniences if the publishing team needs them. They are signals that the workflow has outgrown the tool.

I would reach for a CMS when editors need a browser interface, several people publish independently, approvals matter, content relationships become complex, or updates need to happen without a deployment. At that point, adding a CMS removes friction rather than adding ceremony.

Start with the workflow you have

Architecture is often planned around a future organisation that never arrives. I would rather begin with the smallest system that serves the current team and keep the content model portable.

Clear frontmatter and ordinary Markdown make later migration possible. If the site eventually needs Sanity, WordPress, Contentful, or another platform, the existing files already describe the content structure.

A CMS is valuable when it solves a publishing problem. Until that problem exists, a folder of well-validated text files can be a surprisingly durable system.