Markdown を拡張する MDX はドキュメント作成の新たな可能性？

簡単に独自コンポーネントを使える

JSX (と React) では一つの要素の単位をコンポーネントと呼んでおり、MDX では通常の HTML タグと同じようにユーザーの作ったコンポーネントを使えます。この点では他のテンプレートエンジンと近い機能を備えていますが、ベースとなるテキストが Markdown であることはドキュメントの記法として有利です。

直接 JavaScript として読み込める

MDX を使うことで、原稿として書かれた Markdown は上記の JSX を通して直接 JavaScript としてみなすことができます。これは、React のようなライブラリを使った Web アプリケーションの上で扱う際に非常に便利です。

例えば、あるドキュメントを紙媒体と Web ページ両方に掲載したい状況を考えます。原稿が HTML であれば、もちろんブラウザに表示させることができますが、MDX は一つのコンポーネントとして扱うことができるので、ページの一部分に配置したり、並べて掲載したりすることがとても簡単です。また、フォントやテキスト色を変えるなど、外部からの装飾も既存の CSS にとらわれずに制御できます。

独自コンポーネントを作成する

次に、少し CSS 組版っぽいコンポーネントを作成する例を紹介します。

「縦中横」は、縦書きの文章中に横組みでテキストを挿入する処理のことで、日本語では数桁の数字を縦中横で組むことがあります。このレイアウトは、CSS では text-combine-upright というプロパティで指定しますが、仕様で定められているもののうち実際にブラウザが実装しているものは none と all のみで、桁数に応じて自動で切り替えてくれる digits <integer>? は提供されていません。この問題を、独自コンポーネントで解決してみます。

まず、src/components ディレクトリに Tcy.js ファイル 一般的に JSX ファイルは通常の JavaScript と区別するために .jsx という拡張子を使う慣習がありますが、Gatsby ではどちらでも良いようです を作成し、以下のようなコードを書きます。

import React from 'react';

export const Tcy = ({ number, digits = 2 }) => {
  const textCombineUpright =
    Number.isFinite(number)
    && `${number}`.length <= digits
    ? 'all' : 'none';
  return (
    <span style={{ textCombineUpright }}>
      {number}
    </span>
  );
};

上記の例では、Tcy という名前のコンポーネントを作成しています。number が正しい数字で、テキストで表した際の文字数が digits 以下のとき、text-combine-upright に all を設定するようにしています。

このコンポーネントを MDX ファイルで使用するためには、次のように書きます。

import { Tcy } from '../components/Tcy';

# Hello, world!

<Tcy number={2021} />年
<Tcy number={7} />月
<Tcy number={11} />日

外部のコンポーネントをインポートするときは、JavaScript と同じように import 文を使います。そして、先ほど作成した Tcy コンポーネントに number プロパティを与えます。digits プロパティは省略していますが、同じように与えることができます。

ブラウザーの開発ツールで見てみると、目的通り「7」と「11」にだけ text-combine-upright: all が設定されていることが確認できます。

原稿を SSG で生成する

大げさな前置きを書いた手前で恐縮ですが、前の章で紹介した Gatsby を使っている場合、実はコマンド一つで生成できます。

npm run build

コマンド実行後、public というディレクトリが作成され、この中の index.html というファイルが生成されたドキュメントになります。このディレクトリをそのまま Vivliostyle に与えてあげれば、PDF に変換されます。簡単ですね！

ただし、制約がまったく無いわけではありません。Vivliostyle はドキュメント中の JavaScript を解釈しないので、HTML に埋め込みたいものはすべてビルド時に依存関係を解決させる必要があります。Dynamic import なども使えないので、外部のライブラリを使ったり自分で実装する際は注意が必要です。

Expression 記法

ドキュメントとしては書き起こされていませんが、MDX v2 では新たに Expression の文法が導入されています。JSX では、中括弧 ({}) で囲われた部分を JavaScript の式として評価する文法がありますが、従来これを MDX で使うためには <div></div> のように JSX タグで囲われた部分でしか使えませんでした。v2 では、通常の Markdown の文脈でも直接 {} で囲うことによって、その部分が式として評価されるようになります。これは、インラインの Markdown でも同じように解釈されます。

例えば、以下のような MDX があった場合、

# Hello, {1 + 1}

{
  'mdx'.toUpperCase()
}

JSX として見るとこのように解釈されます。

<h1>Hello, {1 + 1}</h1>
<p>{'mdx'.toUpperCase()}</p>

これが JSX の処理系でレンダリングされると、以下のようになります。

<h1>Hello, 2</h1>
<p>MDX</p>

MDX をドキュメント作成として使う場合、これまでは外部のライブラリはコンポーネントとしてしか読み込めなかったので、使い勝手はあまり良くなかったです。この変更により、インラインで JavaScript の便利な機能を埋め込めるようになるので使い道がぐっと広がっています！

MDAST の変更

上記の変更も含めて、MDX をパースした時に生成される MDAST (Markdown AST) の構造が大きく変わっています。MDX v1 では、MDAST に以下のようなタイプ名のノードが拡張されていました。

jsx import export

一方で、v2 では以下のようなタイプが定義されています。

mdxJsxFlowElement mdxJsxTextElement mdxjsEsm mdxFlowExpression mdxTextExpression

内部的には以下の 3 つのパーサーに分けて実装されているので、それぞれについて見てみます。

<MyComponent {...props}/>

{
  type: 'root',
  children: [
    {
      type: 'mdxJsxFlowElement',
      name: 'MyComponent',
      attributes: [
        {
          type: 'mdxJsxExpressionAttribute',
          value: '...props',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'ObjectExpression',
                    properties: [
                      {
                        type: 'SpreadElement',
                        argument: {type: 'Identifier', name: 'props'}
                      }
                    ]
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        }
      ],
      children: []
    }
  ]
}

import a from 'b'
export var c = ''

{
  type: 'root',
  children: [
    {
      type: 'mdxjsEsm',
      value: "import a from 'b'\nexport var c = ''",
      data: {
        estree: {
          ...
        }
      }
    }
  ]
}

{
  a + 1
}

b {true}.

{
  type: 'root',
  children: [
    {
      type: 'mdxFlowExpression',
      value: '\na + 1\n',
      data: {
        estree: {
          ...
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'b '},
        {
          type: 'mdxTextExpression',
          value: 'true',
          data: {
            estree: {
              ...
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}