Content Collections

In the larger context of the project structure, src/content/ serves as the content repository and data layer for the Astrofy application. It decouples raw written content (like Markdown articles) from visual UI code, allowing content to be managed independently of page templates.

  1. Structure & Purpose of src/content

Instead of hardcoding text into HTML or storing articles in a remote database, dynamic content is stored locally as Markdown (.md) or MDX files organized into subdirectory collections:

  • src/content/blog/.md:* Holds Markdown files for blog articles (such as docker-commands.md or first_homelab.md).
  • src/content/store/: Holds Markdown or JSON entries for digital/physical products.
  • src/content/config.ts: Serves as the central configuration file defining the strict data schema for every collection.
  1. Type Safety & The Content Collections API

Astro interacts with src/content/ through its strongly typed Content Collections API (getCollection):

  • Schema Validation (config.ts): Collections are validated against a schema defined in src/content/config.ts.
  • Extensibility: If you want to add new frontmatter metadata to your blog posts (such as an author name, customDate, or readingTime), you update the schema inside src/content/config.ts. Astro will then enforce type safety across all Markdown files in that collection.
  1. Build-Time Dependencies & Empty Collection Bugs

Because Astro compiles down to static HTML, files in src/content/ are queried at build time by dynamic page routes (like src/pages/blog/[slug].astro) to automatically emit formatted HTML pages and RSS feeds:

  • The @astrojs/sitemap Crash: A critical build dependency highlighted in the project's logs occurs when a collection defined in config.ts or referenced in src/pages/ (such as store) is missing or completely empty on disk.
  • Root Cause: During the production build (npm run build), the @astrojs/sitemap integration attempts to loop through every collection entry to construct a sitemap. When it encounters an empty directory, it hits an undefined dataset and crashes with Cannot read properties of undefined (reading 'reduce'), failing the build.
  • Resolution: Resolving this build failure requires either creating the missing collection folder under src/content/ with at least one valid Markdown file, or deleting the corresponding route files (e.g., src/pages/store/) and disabling the sitemap integration in astro.config.mjs.
  1. Position in the Broader Project Hierarchy
src/
├── content/    <-- Raw Markdown Data & Schema Validation (config.ts)
├── pages/      <-- Queries src/content/ via getCollection() for dynamic routes ([slug].astro)
├── layouts/    <-- Wraps compiled Markdown HTML inside BaseLayout's <slot />
└── components/ <-- Renders content summaries into UI cards (HorizontalCard.astro)

By isolating content inside src/content/, authors can add, edit, or delete articles simply by dropping Markdown files into src/content/blog/. Astro automatically handles sorting, slug creation, tag filtering, and page generation without requiring any changes to the underlying layout or styling architecture.