Sources

A source is the boundary that hands Comark raw content. It's the only required piece of a Content: point the instance at one source, or mount several under names, and everything else (the manifest, cache, plugins) builds on top.

Interface

A source is intentionally tiny. Three methods do the work, and a few optional fields tune behaviour:

interface Source {
  keys: () => Promise<string[]> | string[]
  getItem: (key: string) => Promise<string> | string
  getItemRaw: (key: string) => Promise<unknown> | unknown
  prefix?: string
  schema?: JsonSchema
  watch?: Driver['watch']
}

keys()

List every content key the source exposes, as forward-slash paths with no leading slash (e.g. posts/hello.md). Keys must round-trip: whatever keys() returns is exactly what getItem and getItemRaw receive.

getItem()

Return a key's text content: the raw Markdown (or JSON/YAML) that Comark parses. Throw if the key is unreachable, and the Content instance surfaces the error to the caller.

getItemRaw()

Return a key's raw bytes, as a Uint8Array, for media files. Required even if you only ship documents: return null when a key has no binary form.

prefix

Prepended to every entry's public path, which is handy when a folder owns a slice of the URL space. It does not change the key.

schema

An explicit JSON Schema for the source's data. The Content instance uses it to generate types and query columns. Register the schema-validation plugin to validate documents against it.

watch()

When present, content.watch() forwards the source's change events. Only drivers that implement it fire events (the filesystem source does; remote ones do not).

Single source

Pass source for the common case: one source, mounted under the implicit name default.

const content = comarkContent({ source: fs('./content') })
await content.get('/about')   // resolves to default/about.md

Multiple sources

Pass sources to mount several under names. The name becomes part of every entry's key and is what you pass to list() / navigation() to scope them.

const content = comarkContent({
  sources: {
    docs: github({ repo: 'acme/docs', path: 'content' }),
    blog: fs('./content/blog'),
  },
})
await content.list(['blog'])   // only entries from the blog source