ローカルの Markdown ファイルからデータをフェッチする

Spear はローカルの Markdown ファイルからデータをフェッチできます。
この機能にはいくつかルールがあります。There are some rules for this feature.

基本

Markdown ファイルのフェッチ方法には @spearly/spear-markdown-plugin が必要です。

npm か yarn 経由でインストールできます。

# yarn add @spearly/spear-markdown-plugin

インストール後、spear.config.mjs を修正する必要があります。

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

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

Markdown ファイルの準備

デフォルトでは、@spearly/spear-markdown-pluginが data/ ディレクトリ配下の Markdown ファイルを検索します。
このプラグインは、第一段階で data/ 配下でコンテンツタイプ名と同じディレクトリを検索します。その次のステップとして、data/<content type name>/配下からコンテンツを検索します。
更に、このプラグインはデフォルトで .mdx 拡張子のファイルを検索します。

例えば、content-sample というコンテンツタイプの test というコンテンツが欲しい場合、data/content-sample/test.mdx というファイルを作っておく必要があります。

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.)

コンテンツ埋め込み

Markdown コンテンツをサイトに埋め込む方法は Spearly CMS を利用する方法と同じです。

1. コンテンツリスト

@spearly/spear-makedown-plugin はコンテンツタイプディレクトリ配下のファイル全部のリストを繰り返し生成します。

<!-- 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. コンテンツ

もし、cms-item と cms-content-type そして cms-content 属性が指定されていれば、Spear はプラグインを使って特定の Markdown ファイルからフェッチします。

<!-- 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 フォーマット (フィールドタイプ)

Markdown のフォーマットにはいくつかルールがあります。

• フロントマターはテキストフィールドに変換されます。
• Markdown の本文は body というキー値のリッチテキストに変換されます。

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

Markdown sample

フロントマター

Spear はフロントマターのキーと値をフィールドのアイテム名と値に変換します。すべてのフロントマターはテキストフィールドになります。

Markdown

Markdown 部分はリッチテキストフィールドとなり、フィールド名は body になります。この名前は固定です。注意：

• このプラグインは remark と remark-html を利用しています。このパッケージはテーブルや ToC を生成できません。もし他の unified プロセッサーを使いたい場合、カスタムのプロセッサーを利用できます。カスタムのプロセッサーについては次のセクションを参照してください。
• このプラグインは改行を正しく変換できない場合があります。

プラグインオプション

markdownPlugin 経由でプラグインのオプションを渡すことができます。このプラグインで許可されているオプションは以下のとおりです。

プロセッサー

unified の他のプロセッサーを利用することがd系マス。詳細は unified のドキュメント を参照してください。

例えば、この Spear ドキュメントプロジェクトは文法ハイライトを有効にするため、以下のプロセッサーを利用しています。

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,
    })  ]
}

上記サンプルでは、 Gfm と Toc も利用しています。結果として、このプロジェクトでは Toc やテーブルを上手く生成できます。