Why public content starts with Astro Content Collections and local Markdown

Adding a CMS at the start of a content site often makes the setup feel more complete. For this site, though, the first problems to solve are article identity, language versions, draft boundaries, and public output, not a remote administration interface.

Choosing Astro Content Collections with local Markdown for now does not mean CMSs are bad, nor is it a long-term commitment. The reasoning is narrower: the current volume of public notes and the way we collaborate do not yet justify adding a database, authentication, permissions, and a separate publishing system just to get an editing interface. Establishing a reliable content contract first costs less and is easier to verify.

Start with what the content actually needs

The notes are currently part of the website, not a data service that handles real-time transactions. Articles need:

• A stable identity so that language versions of the same article can be matched.
• slug and locale fields so that each language has its own URLs.
• draft, publishedAt, and updatedAt fields that describe content state and dates separately.
• Metadata such as category, tags, title, description, and author.
• Public pages rendered as HTML at build time, with drafts available for local preview.

Markdown frontmatter and a Content Collection schema can express all these requirements. Adding a CMS at this stage would address remote editing and management; it would not automatically decide article identity, language relationships, or which content can be made public.

Content Collections provide a content contract

Local Markdown does not mean the data can be written without rules. Astro’s collection loader reads articles under src/content/notes/, and the schema validates each file’s frontmatter.

The current data flow can be simplified to:

Local Markdown
  → Content Collection loader
  → noteSchema
  → getAllNotes()
  → getPublishedNotes()
  → Homepage, listing, article pages, and sitemap

The schema constrains locale, slug, date formats, and the currently supported category. It also rejects a non-draft article without publishedAt. The article queries separately check for duplicate slug and stableId values within a language, and ensure that the file’s language directory matches its locale.

These checks keep Markdown readable without leaving authors to guess the structure of every article. The files are the content source, the schema defines the content boundaries, and the publishing queries define eligibility for public output.

Why keep content in the repository for now

Content and its versions can be reviewed together

Articles live in the same project as the site’s layouts, routes, and validation scripts. To trace why an article has a particular field or which page uses it, we can work backward through the content model and its use sites. We do not have to sign in to another system first and compare remote data.

This also allows article changes to be reviewed separately from code changes. Adding an article can involve checking just the Markdown and content validation; changing publishing rules requires checking the pages and sitemap as well. The responsibilities are still different, but the data source is not hidden in a separate administration system.

Public output does not need runtime queries

The site currently produces static output. The production build reads the articles and generates the homepage, listings, article detail pages, and sitemap. The browser receives HTML that has already been generated, so it does not need to query a content API when a reader opens a page.

This does not mean static output is necessarily faster or that search results will necessarily improve. What we can confirm is that article eligibility and page output are determined within the same build process, leaving one less runtime content service to maintain.

Draft boundaries are more direct

Local previews can read all valid Markdown, but public pages read only articles eligible for publication. Keeping a draft in a file does not automatically give it a public route. Only articles that satisfy the draft, publishedAt, and publication-date conditions enter the public collection.

This lets content review proceed while the public site continues to contain only confirmed articles. A CMS can enforce this boundary too, but at the current volume, files, a schema, and query functions are enough to express it.

What this choice deliberately leaves out

Local Markdown has clear costs. It does not currently provide:

• An article editor in the browser.
• An administration interface that nontechnical editors can sign in to and edit directly.
• A remote publishing workflow that updates content immediately without rebuilding.
• Built-in account, permission, comment, or subscription management.
• Full-text search, review workflows, or a version comparison interface supplied automatically by the content system.

These are not hidden features; they are capabilities outside the current scope. As long as authorship, review, and publication can still be handled through the repository and local previews, choosing not to take on the complexity of those systems is a deliberate trade-off.

Public notes and product data also need to be kept separate. Build-time content suits articles. Accounts, financial data, and data that needs to be saved immediately after a user action should not be put into Markdown merely because the website uses it.

When to reassess a CMS

A CMS or another content service would be worth reassessing if these needs arise:

• Multiple authors or editors who do not modify the repository directly.
• Frequent, immediate article publication by non-developers.
• Content review, permissions, scheduling, or version comparison becoming routine work.
• Article volume and query requirements growing beyond what local files can comfortably support.
• Sharing the same content with products, apps, or APIs outside the website.

Under those conditions, a CMS may reduce the actual workload. Even then, adopting one would require redesigning stable IDs, language versions, publication eligibility, caching, previews, and output validation. Moving to an administration interface does not remove the content contract; it moves the content source from files to another system.

Conversely, an article list in a mockup, or the possibility of more articles in the future, is not enough evidence that a CMS is needed now. The place content occupies in an interface describes how readers will navigate it, not a demonstrated need for a management system.

What this architecture can currently demonstrate

The current loader, schema, query functions, page routes, and output validation establish that:

• Markdown articles can enter the Content Collection with controlled metadata.
• Public pages use the published collection rather than treating every file as public content.
• Language versions can be matched through stableId, while URLs are still determined by each language’s slug.
• Drafts can be previewed in Astro dev, and the production build does not register preview routes.
• The homepage, listings, article pages, and sitemap can share the same publication-eligibility rules.

That evidence does not establish that:

• Local Markdown is better than a CMS for every team.
• The content volume will never grow enough to require an administration interface.
• Readers necessarily prefer a file-based content workflow.
• Static output has already demonstrated performance, SEO, traffic, or business results.

The current choice answers a narrower question: given this content volume, this way of collaborating, and these static publishing boundaries, which content source is easiest to get right and verify first?

Keeping the content source small does not lock in the future

As long as article identity, language versions, and publication eligibility are not hard-coded into a particular page, the same public contract can survive a future change of content source. What deserves to be established first is what counts as the same article, which version can be made public, where pages read their content, and how the output is verified.

For now, Astro Content Collections with local Markdown gives us a smaller system boundary while these contracts are sufficient and the extra capabilities of a CMS have not yet been justified by actual needs. When content work really calls for a different tool, we can reassess it against those new needs rather than paying maintenance costs for an imagined scale in advance.

Scope of this record

This article is based on the current Content Collection loader, note schema, article queries, preview integration, page routes, sitemap, and studio development specification. It explains why a CMS is not being introduced first and what limitations that decision retains. It does not claim that CMSs are unsuitable for other content teams, or describe a future administration interface, search, or remote publishing as features that already exist.