YAML Plugin

yaml is the YAML counterpart of json. Each .yaml / .yml file becomes a ContentFile whose data is the parsed YAML object and whose nodes are empty.

Usage

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

const content = comarkContent({
  source: fs('./content'),
  plugins: [yaml()],
})

Given content/config/site.yaml:

name: Acme
tagline: "Build: faster"
theme: dark

const config = await content.get('/config/site')
config?.data  // { name: 'Acme', tagline: 'Build: faster', theme: 'dark' }

API

yaml(options?)

Returns a ContentPlugin that registers a parser for .yaml and .yml files. Each file becomes a kind: 'document' ContentFile whose data is the parsed YAML object and whose nodes are empty. Files that fail to parse, or that parse to an array (rather than an object), are handled according to onError — by default they are dropped with a warning.

Parameters:

• options?: see Options.

Returns: ContentPlugin

Options

listingFields

By default a listing keeps a document's whole data object. Pass listingFields to limit which data keys are retained in content.list() results for .yaml / .yml entries, forwarded to content.addListingFields():

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

yaml({
  listingFields: ['name', 'theme'],
})

Default: undefined

onError

How the parser reacts when a .yaml / .yml file can't be parsed or isn't an object: 'warn' logs and drops it, 'ignore' drops it silently, 'throw' aborts. Defaults to the Content-level onError (which defaults to 'warn').

yaml({ onError: 'throw' }) // fail fast on malformed YAML

Default: the Content instance onError option

Read data

Each .yaml / .yml file resolves to a regular kind: 'document' ContentFile whose data is the parsed object, so the core content methods (content.get(), content.list(), content.stat(), and content.navigation()) treat them like any other document, and content.query() indexes their flattened data.

const config = await content.get('/config/site')
config?.data.theme  // 'dark'

Trim listings

When a source serves large YAML records, restrict listings to the fields you actually render:

const content = comarkContent({
  source: fs('./content'),
  plugins: [yaml({ listingFields: ['name', 'theme'] })],
})

await content.list(['default'])
//    → each YAML entry's data is trimmed to { name, theme }