Media Plugin

Serve binary files (images, fonts, videos) from your source so they can live alongside your content.

The media plugin teaches the Content instance to recognise binary files (images, fonts, video, PDFs) as kind: 'media' entries. They are listed alongside documents in the manifest and their bytes can be served at their public path.

Usage

content.ts

import { comarkContent } from 'comark-content'
import media from 'comark-content/plugins/media'

const content = comarkContent({
  source: github({ repo: 'org/assets', branch: 'main', path: 'public', prefix: '/assets' }),
  plugins: [media()],
})

The plugin adds a content.media namespace. Read an item's metadata with content.stat() and its bytes with content.media.get(), then serve them with the correct content type:

serve-media.ts

const item = content.stat('/assets/logo.svg')
//    ^? ContentListFile - { path: '/assets/logo.svg', data, meta: { kind: 'media', type: 'image/svg+xml', ... } }

const raw = await content.media.get('/assets/logo.svg')
//    ^? unknown: the raw bytes (Uint8Array | string), or null

// In a Nitro / Express handler:
return new Response(raw, { headers: { 'content-type': item.meta.type } })

The Vite plugin emits every media entry into the build output, so the same URLs your client uses in dev resolve as static assets in production.

API

`media(options?)`

Returns a ContentPlugin that registers a parser for the configured extensions (marking matching files as kind: 'media') and adds the content.media.get() and content.media.list() methods.

Parameters:

options?: see Options.

Returns: ContentPlugin

`content.media.get(key)`

Added by the plugin. Fetches the raw bytes of a media item by path or key. Calls content.init(), resolves the item via content.stat(), then reads it from its source.

Parameters:

key: string, the media item's path or key.

Returns: Promise<unknown> - the raw bytes (Uint8Array or string at runtime), or null when no matching item exists.

`content.media.list(sources?)`

Added by the plugin. Lists every kind: 'media' entry in the manifest, optionally limited to specific sources.

Parameters:

sources?: string[], source names to list media from. When omitted, entries from all sources are returned.

Returns: Promise<ContentListFile[]>

Options

Option	Type	Default	Description
`extensions`	`.${string}`[]	`DEFAULT_MEDIA_EXTENSIONS`	File extensions to recognise as media.

`extensions`

The list of file extensions the plugin registers as media. When omitted, the built-in DEFAULT_MEDIA_EXTENSIONS list is used:

['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico', '.bmp',
 '.mp4', '.webm', '.ogg', '.mp3', '.wav', '.aac', '.pdf']

MIME types are looked up from an internal MIME type map. To override the list (for instance to drop .pdf or add .woff2) pass extensions:

override.ts

import media from 'comark-content/plugins/media'

media({
  extensions: ['.png', '.svg', '.webp', '.mp4', '.woff2'],
})

extensionsreplaces the default list rather than extending it. Include every extension you want to recognise.

Default: DEFAULT_MEDIA_EXTENSIONS

Full-text Search

Index every heading as a searchable section and add `content.search()` and `content.resetSearchIndex()` to the Content instance.

JSON

Handle `.json` files as data documents to query with `content.get`, `content.list`, and SQL.