Content Loader API

          
            ## Astro Content Loader API Guidelines

1.  Purpose: Loaders bridge data sources (local files, APIs, CMS, databases) with Astro's Content Collections system. They define _how_ data gets into a collection.

2.  Association: Each content collection defined in `src/content/config.ts` requires a `loader`.

3.  Built-in Loaders:

    - `glob({ pattern, base?, generateId? })`: Loads entries from directories of files (Markdown, MDX, Markdoc, JSON, YAML) based on a glob pattern relative to the `base` path. [Reference](mdc:https:/docs.astro.build/en/reference/content-loader-reference/#glob-loader)
    - `file({ filename, generateId? })`: Loads entries from a single JSON or YAML file. [Reference](mdc:https:/docs.astro.build/en/reference/content-loader-reference/#file-loader)

4.  Custom Loaders: Can be defined inline in `src/content/config.ts` or as reusable "Object Loaders".

5.  Object Loader API: A custom loader is an object with a `name` and a `load` function. [Reference](mdc:https:/docs.astro.build/en/reference/content-loader-reference/#object-loader-api)

    - `name`: `string` - A unique identifier for the loader.
    - `load`: `async (context: LoaderContext) => void` - The core function responsible for fetching, parsing, and storing data.

6.  `LoaderContext` (passed to `load`): Provides tools for the loader. Key properties include:

    - `store`: `DataStore` - Interface to manage entries _within the specific collection_ the loader is assigned to.
    - `logger`: `Logger` - For outputting informational or debug messages during the load process.
    - `parseData`: `async ({ id, data }) => Promise<ParsedData>` - Crucial function. Validates raw fetched data against the collection's Zod schema and parses it into the expected typed format. Must be called before `store.set()`.
    - `generateDigest`: `(data) => string` - Creates a non-cryptographic hash of data, useful for the `digest` property on `DataEntry` to track changes.
    - `watcher`: `FSWatcher | undefined` - In dev mode, provides access to a filesystem watcher to trigger reloads (e.g., when a source file changes).
    - `config`: `AstroConfig` - The resolved Astro project configuration.

7.  `DataStore` API: Methods to interact with the collection's key-value store. [Reference](mdc:https:/docs.astro.build/en/reference/content-loader-reference/#datastore)

    - `set(entry: DataEntry)`: Adds or updates an entry _after_ it has been processed by `parseData`. Uses the `digest` property, if present, to avoid unnecessary updates if content hasn't changed.
    - `get(id: string)`: Retrieves an entry by ID.
    - `delete(id: string)`: Removes an entry.
    - `clear()`: Removes all entries (useful before loading fresh data).
    - `has(id: string)`: Checks if an entry exists.
    - `entries()`, `keys()`, `values()`: Iterate over stored entries.

8.  `DataEntry` Object: The structure representing a single item within the collection store. [Reference](mdc:https:/docs.astro.build/en/reference/content-loader-reference/#dataentry)
    - `id`: `string` (required) - Unique identifier within the collection.
    - `data`: `Record<string, unknown>` (required) - The _parsed_ data conforming to the collection's schema (result of `parseData`).
    - `filePath`: `string | undefined` - Relative path to the source file (if applicable, e.g., for `glob`). Used for resolving assets like images within the entry.
    - `body`: `string | undefined` - Raw, unparsed content body (e.g., Markdown source before rendering).
    - `digest`: `string | undefined` - Content hash generated by `generateDigest` for change detection.
    - `rendered`: `RenderedContent | undefined` - Object containing pre-rendered `html` and `metadata` (like `headings`, `imagePaths`). If present, allows the entry to be rendered using `<Content />` or `render()`.

Reference: [Astro Content Loader API Docs](mdc:https:/docs.astro.build/en/reference/content-loader-reference)