Zennの記事作成にtextlintを導入した話
Zennの記事を作成する際、間違った日本語や表記揺れが起きてしまうことがあります。記事ごとに確認するのは大変ですし、自分の中で統一されていないということに気づくこともできません。
そこで、textlintを導入して、記事作成時に自動でチェックするようにしました。
textlintとは
textlintは、テキストをチェックするツールです。設定したルールに従って、表記揺れや間違った日本語をチェックしてくれます。導入自体も簡単です。
その中で、技術書向けのルールセットがあります。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
私は彼は好きだ
この場合、以下のようなエラーが出力されます。それぞれ技術書向けルールのエラーです。
一文に二回以上利用されている助詞 "は" がみつかりました。
文末が"。"で終わっていません。
ルールのカスタマイズ
技術書向けルールセットには、多くのルールが設定されています。これらのルールをカスタマイズできます。
筆者は以下のような設定にしています。
"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?
}
カスタムルールの作成
独自のルールを設定できます。筆者は、以下のルールを追加しました。
パターンに当てはまるものを、期待するものに置換するように設定しています。
version: 1
rules:
- expected: 筆者は
pattern: 私は
- expected: 筆者が
pattern: 私が
- expected: はじめに
pattern: 初めに
- expected: さいごに
pattern: 最後に
設定ファイルにはルール定義したファイルまでのパスを記述します。
これで独自ルールが適応されます。
"rules": {
"prh": {
"rulePaths": [
"./rules.yml"
]
},
"preset-ja-technical-writing": {
...
}
}
Huskyで最終チェック
ルールの見過ごしがある可能性を見越して、最終的にHuskyでチェックするようにしました。
lint-stagedを導入し、mdファイルのみをチェックするようにしています。
npx lint-staged
"lint-staged": {
"*.md": [
"npx textlint --fix ./articles/*.md"
]
},
husky、lint-stagedの導入方法は公式を確認してください。
さいごに
筆者はtextlintを導入し、記事作成時に自動でチェックするようにしました。これにより、間違った日本語や表記揺れが起きることを防ぐことができました。
みなさんも技術書を書く際に、textlintを導入してみてはいかがでしょうか。
Discussion