Fetching data from local markdown file

Spear can fetch data from local markdown files.
There are some rules for this feature.

Basic

The way of fetching markdown file need @spearly/spear-markdown-plugin.

You can install via npm or yarn.

# yarn add @spearly/spear-markdown-plugin

After installing plugin, you should modify the spear.config.mjs:

import { markdownPlugin } from "@spearly/spear-markdown-plugin";

export default {
  ...
  "plugins": [
    markdownPlugin(),
  ]
}

Prepare the markdown file

By default, @spearly/spear-markdown-plugin search the markdown file under data/ directory.
This plugin search the directories which has same name to content type under data/ as first step, then next step is searcing contents from the directory under the data/<content type name>/.
Furthermore, this plugin use .mdx file extension for searching by default.

For example, we want to the content-sample content type and test contnet alias document, we need create the data/content-sample/test.mdx file.

data
  |- <content-sample>
  |        |- test1.mdx (This document's content type is content-sample and content alias is test1.)
  |        |- test2.mdx (This document's content type is content-sample and content alias is test2.)
  |        |- test3.mdx (This document's content type is content-sample and content alias is test3.)

Embed content

The way to embed markdown content to the site is same the way to use Spearly CMS.
We will explain the field type after this section.

1. content list

@spearly/spear-makedown-plugin will repeat generating list in whole of the files under content type directory.

<!-- This syntax will generate title list from /data/content-sample directories. -->
<div cms-loop cms-content-type="content-sample">
  <h1>{%= content-sample_title %</h1>
</div>

2. content

If specify cms-item and cms-content-type and cms-content, Spear will fetch specified markdown by using this plugin.

<!-- This syntax will generate title of specific data from /data/content-sample/test1.mdx -->
<div cms-item cms-content-type="content-sample" cms-content="test1">
  <h1>{%= content-sample_title %</h1>
</div>

Markdown format (Field type)

There are some rule of markdown format:

• Front-matter will convert to be text field.
• Markdown body will convert to be rich text with body key.

---
title: Hello world!
---
# sample

Markdown sample

Front-matter

Spear convert the key and value of front-matter to field's item name and item value.
All of front-matter will be text field type.

Markdown

Markdown part will be rich text field type, then field name is body. This name is fixed.
Note that

• This plugin use the remark and remark-html. This packages can't generate table, toc, If you use an another unified processor, you can use custom processor. For detail, see the next section.
• This plugin can't convert line-break string correctly.

Plugin options

You can pass the plugin option via markdownPlugin paramter. This plugin allow the followoing options:

processor

You can use other unified processor, For detail, see unified document.

For example, this Spear document project use the following processor in order to add highlight.

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import remarkToc from "remark-toc";
const processor = unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(remarkToc)
  .use(rehypeStringify)

export default {
  ...
  "plugins": [
    markdownPlugin({      processor: processor,
    })  ]
}

In above sample, use Gfm and Toc. As result of this line, this project generate tabel and ToC corectlly.