---
title: "Markdown Plugin"
description: "Parse Markdown documents with Comark and keep only selected frontmatter fields in listings."
canonical_url: "https://content.comark.dev/plugins/built-in/markdown"
---
# 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](https://comark.dev). It stores frontmatter in `file.data`, the parsed body in `file.nodes`, and parser metadata in `file.meta`.

## Default behavior

[`comarkContent()`](https://content.comark.dev/reference/content/comark-content) 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`:

```ts [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](https://content.comark.dev/reference/content/comark-content#options-markdown) is passed to this automatically installed plugin.

## Configure the plugin explicitly

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

```ts [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'],
    }),
  ],
})
```

::warning
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

The plugin is a single factory:

### `markdown(options?)`{lang="ts"}

Returns a [`ContentPlugin`](https://content.comark.dev/reference/types/plugins#contentplugin) that registers the `.md` and `.markdown` parsers.

**Parameters:**

- `options?`: see [Options](#options).

**Returns:** [`ContentPlugin`](https://content.comark.dev/reference/types/plugins#contentplugin)

---

## Options

`markdown(options?)` accepts two options:

| Option                                    | Type            | Default     | Description                                                                              |
| ----------------------------------------- | --------------- | ----------- | ---------------------------------------------------------------------------------------- |
| [`comark`](#options-comark)               | `ParserOptions` | `undefined` | Comark plugins and parse options used for Markdown bodies.                               |
| [`listingFields`](#options-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](https://comark.dev/api/parse) 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()`](https://content.comark.dev/reference/content/list), and [`content.navigation()`](https://content.comark.dev/reference/content/navigation) payloads unnecessarily large.

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

```ts [content.ts]
markdown({
  listingFields: ['title', 'description', 'navigation'],
})
```

This applies to both `.md` and `.markdown` files and is forwarded to [`content.addListingFields()`](https://content.comark.dev/reference/content/add-listing-fields). It only trims the lightweight listing entry: [`content.get()`](https://content.comark.dev/reference/content/get) still returns the document's complete frontmatter after loading the full file.

**Default:** `undefined`


## Sitemap

See the full [sitemap](https://content.comark.dev/sitemap.md) for all pages.