README

`@directdb/markdown-handler`

Markdown file handler w/ YAML front matter for DirectDB.

The handler passes the markdown through as a string while parsing the front matter as YAML. It uses yaml under the hood for parity with @directdb/yaml-handler.

Install

npm i @directdb/markdown-handler
# OR
yarn add @directdb/markdown-handler

Usage

The main package directdb already includes @directdb/markdown-handler.

If you want to create your own variant of DirectDB with this handler, you can compose one with @directdb/core.

import directdb from '@directdb/core'
import markdownHandler from '@directdb/markdown-handler'

const db = await directdb('.', { fileHandlers: [markdownHandler] })

The Markdown Document

The return type of the file handler is called a Markdown Document. It is an object with a markdown key containing the markdown as a string and a frontMatter object containing parsed YAML front matter:

await db.readFile('$/foo.md')
{
  markdown: "# Hello!",
  frontMatter: { some: 'data' }
}

YAML Front Matter

Plain markdown can be created by passing a string to db.createFile:

await db.createFile('$/foo.md', '# Lorem Ipsum')

Files can also be created with YAML front matter by passing an object with markdown and frontMatter keys to createFile:

const markdown = '# Lorem Ipsum'
const frontMatter = ['some', 'meta', 'data']

await db.createFile('$/foo.md', { markdown, frontMatter })

⚠️ Note that when using updateFile, passing only markdown will delete any front matter:

const markdown = '# Lorem Ipsum'
const frontMatter = ['some', 'meta', 'data']

await db.createFile('$/foo.md', { markdown, frontMatter })
await db.updateFile('$/foo.md', '# New Content') // front matter was removed

Passing only front matter will throw an error.

If you want to update markdown or front matter while preserving the other, both of them are in the file's content:

const { frontMatter } = await db.readFile(['$/foo.md']).content

await db.updateFile('$/foo.md', { markdown: '# New Content', frontMatter })

Options

The handler accepts the following options:

const options = {
  delimiter: '---',
  yaml: {},
}

options.delimiter is passed to light-matter's parse and stringify methods.
options.yaml is passed directly to yaml's parse and stringify methods, just like in @directdb/yaml-handler. See the yaml library docs for full options.

Customize your file handler options like so:

import directdb from 'directdb'
import markdownHandler from '@directdb/markdown-handler'

markdownHandler.options = {
  delimiter: '+++',
  yaml: { prettyErrors: true },
}

const db = await directdb({ fileHandlers: [markdownHandler] })

Options Type Definition

The package exports the TypeScript type interface of this options object. In .ts files you can import this type as a helper for constructing the options object:

import * as MarkdownFile from '@directdb/markdown-handler'

const options: MarkdownFile.Options = {
  /* options*/
}

Usage no npm install needed!