Why I switched to folder-based content entries

One of the most common long-term problems in small content sites is starting too flat. A single .mdx file per entry feels fast at first, but becomes awkward as soon as real supporting material appears.

The real issue is not visual mess

Flat files fail because they make relationships fragile:

• a cover image lives somewhere else
• multilingual variants are easy to lose track of
• attachments and diagrams have no obvious home
• deleting or moving an entry risks leaving stray files behind

You do not need hundreds of entries before this starts to hurt. A dozen entries with a few assets is often enough.

Why folders are a better default

The current model allows an entry to live like this:

content/blog/zh/organizing-content-by-entry-folder/
  index.mdx
  cover.png
  diagram.svg
  notes.md

That makes it much easier to reason about ownership: if a file belongs to this entry, it lives in this folder.

Does Next.js need extra handling for this

Not for the folder structure itself.

In a setup like this one, based on App Router plus direct MDX imports, Next.js does not need extra routing rules just because entries live in folders.

What you do need is a discovery strategy. In this project that discovery layer is intentionally simple: a manual content registry in code.

The same pattern also works for private knowledge

The knowledge base is not published to the site, but it can still follow the same folder-first structure.

That means blog posts, project studies, and internal notes can share one organizational model even if they do not share the same publishing surface.