📝

textlintでMDXを校正するプラグインを作成した

2024/04/09に公開

Markdown

はじめに

textlintという自然言語の文書校正(Lint)ができるツールでMDXを校正するためのプラグインを作成したので紹介いたします。

使用する場合は以下のコマンドで依存関係に追加し、.textlintrcにMDXプラグインの設定を追加してください。

# npm
npm install textlint-plugin-mdx

# Yarn
yarn add textlint-plugin-mdx

# pnpm
pnpm add textlint-plugin-mdx

# Bun
bun add textlint-plugin-mdx

.textlintrc

{
  "plugins": {
    "mdx": true
  }
}

MDXについて

MDXとはMarkdownでJSXを扱えるようにした拡張構文です。拡張子は.mdxです。

https://mdxjs.com/

MDXは近年話題のAstroやDocusaurusでサポートされているなど現在も知名度が上がりつつあります。詳細や使用例は他の記事をご参照ください。

https://zenn.dev/topics/mdx

textlintでMDXをLintするときの課題

textlintではテキストファイルをASTに変換してLintを行うため、構文に対応するプラグインが必要になります。Markdownについては公式にプラグインが提供されていますが、MDXについてはプラグインが存在しなかったため、Markdownのプラグインの設定で.mdxをLintの対象に追加し、MDXファイルをMarkdownとして処理させることが一般的でした。

しかし、この方法ではMDXの独自構文が正しくパースされないため、JSXがLint対象となってしまったり、textlint-filter-rule-commentsのようなMDXでサポートされていないMarkdownの構文を前提とした機能が利用できない課題がありました。

MDXの独自構文の対応

MDX v2以降で導入されているmdastノードは以下の通りです。これらのノードの処理をMarkdownのプラグインに追加しました。textlintのASTについては公式ドキュメントのTxtAST Interfaceをご覧ください。

mdast-util-mdx-expression

MdxFlowExpression

MdxTextExpression

mdast-util-mdx-jsx

MdxJsxFlowElement

MdxJsxTextElement

mdast-util-mdxjs-esm

MdxjsEsm

コメントの例外処理

HTMLのコメント表現をサポートしていないMDXでtextlint-filter-rule-commentsを使用するために、{/* */}をCommentノードとして扱うようにしました。

使用例は以下の通りです。

This is error text.

{/* textlint-disable */}

This is ignored text by rule.
Disables all rules between comments

{/* textlint-enable */}

This is error text.

textlint-filter-rule-commentsでは、以下のコードの通りHTMLノードのの内部またはCommentノードをコメントとして扱うようになっているため、{/*  */}のように記述している方が多かったと思われます。MDXプラグインでは{/* */}がCommentノードとして解釈されるため、回避策を行わずに正常に利用できるようになっています。

おわりに

バグ報告や機能の提案、Pull Requestなど、皆様のContributionをお待ちしております。