Markdown Plugin

Parse Markdown documents with Comark and keep only selected frontmatter fields in listings.

The markdown plugin parses .md and .markdown files with Comark. It stores frontmatter in file.data, the parsed body in file.nodes, and parser metadata in file.meta.

Default behavior

comarkContent() installs the Markdown plugin automatically when no plugin has registered a parser for .md files. For the common case, you do not need to add it to plugins:

content.ts

import { comarkContent } from 'comark-content'
import fs from 'comark-content/sources/fs'
import highlight from 'comark/plugins/highlight'

const content = comarkContent({
  source: fs('./content'),
  markdown: {
    plugins: [highlight()],
    autoClose: true,
  },
})

The top-level markdown option is passed to this automatically installed plugin.

Configure the plugin explicitly

Add markdown() yourself when you need its listingFields option. Once you register it explicitly, pass the Comark parse options to markdown({ comark }), not to the top-level comarkContent({ markdown }) option:

content.ts

import { comarkContent } from 'comark-content'
import fs from 'comark-content/sources/fs'
import markdown from 'comark-content/plugins/markdown'
import highlight from 'comark/plugins/highlight'

const content = comarkContent({
  source: fs('./content'),
  plugins: [
    markdown({
      comark: {
        plugins: [highlight()],
        autoClose: true,
      },
      listingFields: ['title', 'description', 'navigation'],
    }),
  ],
})

When markdown() is present in plugins, the automatic fallback is not installed. A top-level comarkContent({ markdown }) value is therefore not forwarded to your explicit plugin; configure comark inside markdown() as shown above.

API

`markdown(options?)`

Returns a ContentPlugin that registers the .md and .markdown parsers.

Parameters:

options?: see Options.

Returns: ContentPlugin

Options

Option	Type	Default	Description
`comark`	`ParserOptions`	`undefined`	Comark plugins and parse options used for Markdown bodies.
`listingFields`	`string[]`	`undefined`	Frontmatter fields kept in manifest and listing entries for `.md` and `.markdown` files.

`comark`

Passes parse options to Comark when the full Markdown body is loaded. See Comark parse options for the complete API.

Default: undefined

`listingFields`

By default, the complete frontmatter object is stored in every manifest entry and returned by listing APIs. On sites with many Markdown files or large frontmatter objects, this can make the manifest, content.list(), and content.navigation() payloads unnecessarily large.

Use listingFields to keep only the fields needed to identify and render listings:

content.ts

markdown({
  listingFields: ['title', 'description', 'navigation'],
})

This applies to both .md and .markdown files and is forwarded to content.addListingFields(). It only trims the lightweight listing entry: content.get() still returns the document's complete frontmatter after loading the full file.

Default: undefined

JSON

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

YAML

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