📝

Zennの記事作成にtextlintを導入した話

2023/04/15に公開

Zennの記事を作成する際、間違った日本語や表記揺れが起きてしまうことがあります。記事ごとに確認するのは大変ですし、自分の中で統一されていないということに気づくこともできません。

そこで、textlintを導入して、記事作成時に自動でチェックするようにしました。

textlintとは

https://textlint.github.io/

textlintは、テキストをチェックするツールです。設定したルールに従って、表記揺れや間違った日本語をチェックしてくれます。導入自体も簡単です。

その中で、技術書向けのルールセットがあります。textlint-rule-preset-ja-technical-writingモジュールをインストールすることで、技術書向けのルールセットが使えるようになります。

https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing

textlintの導入

基本的に公式のドキュメントに従って導入すればOKです。

# 必要なモジュールをインストール
$ npm install -D textlint textlint-rule-preset-ja-technical-writing
# textlintの設定ファイルを作成
$ npx textlint --init

実例

例えば以下の文章をチェックします。実行コマンドは以下です。

$ npx textlint ./example.md
example.md
私は彼は好きだ

この場合、以下のようなエラーが出力されます。それぞれ技術書向けルールのエラーです。

一文に二回以上利用されている助詞 "は" がみつかりました。
文末が"。"で終わっていません。

ルールのカスタマイズ

技術書向けルールセットには、多くのルールが設定されています。これらのルールをカスタマイズできます。
筆者は以下のような設定にしています。

.textlintrc
"rules": {
  "preset-ja-technical-writing": {
    "ja-no-mixed-period": {
      "allowPeriodMarks": [
        ":"
      ]
    },
    "no-exclamation-question-mark": {
      "allowHalfWidthExclamation": true
    }
  }
}

ja-no-mixed-periodは、文末の句点(。)の統一 OR 抜けをチェックするtextlintルールです。
ここでは、コロン(:)を許可しています。Zennマークアップ時にmessageタグを使用する際に、コロンを使用するためです。

:::message
...
::: ←コロンが必要

no-exclamation-question-markは、感嘆符や疑問符の統一をチェックするtextlintルールです。デフォルトでは、許可していません。
ですが、GraphQLの型定義で、!?を使用することがあります。そのため、半角の感嘆符や疑問符を許可するように設定しています。

type User {
  id: ID!
  name: String!
  age: Int?
}

カスタムルールの作成

独自のルールを設定できます。筆者は、以下のルールを追加しました。
パターンに当てはまるものを、期待するものに置換するように設定しています。

rules.yml
version: 1
rules:
  - expected: 筆者は
    pattern: 私は
  - expected: 筆者が
    pattern: 私が
  - expected: はじめに
    pattern: 初めに
  - expected: さいごに
    pattern: 最後に

設定ファイルにはルール定義したファイルまでのパスを記述します。
これで独自ルールが適応されます。

.textlintrc
"rules": {
  "prh": {
    "rulePaths": [
      "./rules.yml"
    ]
  },
  "preset-ja-technical-writing": {
    ...
  }
}

Huskyで最終チェック

ルールの見過ごしがある可能性を見越して、最終的にHuskyでチェックするようにしました。
lint-stagedを導入し、mdファイルのみをチェックするようにしています。

pre-commit
npx lint-staged
package.json
"lint-staged": {
  "*.md": [
    "npx textlint --fix ./articles/*.md"
  ]
},

husky、lint-stagedの導入方法は公式を確認してください。
https://typicode.github.io/husky/#/?id=automatic-recommended
https://github.com/okonet/lint-staged

さいごに

筆者はtextlintを導入し、記事作成時に自動でチェックするようにしました。これにより、間違った日本語や表記揺れが起きることを防ぐことができました。

みなさんも技術書を書く際に、textlintを導入してみてはいかがでしょうか。

Discussion