textlintを使用して文章のチェックを行う

2022-05-31 / Textlint, 開発環境

仕様書やブログ記事などの文章をできるだけ変にならないように気をつけて書きたいので textlint を使用してチェックを行うように設定してみました。

textlint のインストール

textlint でチェックするルールは別のパッケージとしてインストールして利用するようなので、必要そうなチェック項目とプリセットもインストールします。プリセットは Zenn の導入記事をいくつか拝見したなかで利用されているパッケージを参考に、以下のパッケージを利用することにしました。

textlint 本体と利用するパッケージをインストールします。

npm install --save-dev textlint \
  textlint-rule-no-todo \
  textlint-rule-no-dead-link \
  textlint-rule-preset-ja-technical-writing \
  textlint-rule-preset-ja-spacing

ちなみに textlint-ja/textlint-rule-preset-japanese というプリセットもあります。textlint-ja/textlint-rule-preset-ja-technical-writing の方で設定されているルールと被る部分があるようなので使用しませんでした。

完成した設定ファイル

最終的に以下のような設定になりました。.textlintrc として保存しプロジェクトに配置しています。

{
  "plugins": {
    "@textlint/markdown": {
      "extensions": [".md"]
    }
  },
  "rules": {
    "textlint-rule-no-todo": true,
    "no-dead-link": {
      "ignore": ["https://example.com/**"]
    },
    "preset-ja-technical-writing": {
      "sentence-length": {
        "max": 150
      },
      "no-doubled-joshi": {
        "allow": ["か"]
      }
    },
    "preset-ja-spacing": {
      "ja-space-between-half-and-full-width": {
        "space": "always"
      },
      "ja-space-around-code": {
        "before": true,
        "after": true
      }
    }
  }
}

以下で設定内容を説明します。

ルールの説明

textlint 関連のパッケージ（特にプリセット）は導入した後、自分の文章のスタイルに合わせて個別のルールの設定をする必要があります（ない場合もあります）。

textlint-rule-no-todo

文章中に TODO リストを含まないようにするルールです。仕様書やブログ記事の観点では TODO が含まれるのはおかしい気がするので導入しました。特に細かい設定は不要でした。

textlint-rule-no-dead-link

デッドリンクを検知してくれるルールです。デッドリンクの検知目的というよりはリンクの URL ミスで参照先が存在しないといったものを防げるのではと思い利用しています。https://example.com/ で始まる URL は無視するように設定しました。

ただ、デッドリンクの検出を lint で対応すべきかは疑問です。

textlint-rule-preset-ja-technical-writing

textlint-rule-preset-ja-technical-writing は技術文書向けの textlint ルールプリセットで、デフォルト設定は厳しめになっているそうです。個別に確認しながら設定を緩めていく形になります。

textlint-rule-sentence-length
- 一文あたりに許される文字数のルール
- パッケージ名やインラインコードを含む場合などにデフォルトの 100 文字でははみ出すケースがたびたびあったため 150 字を上限にしました
textlint-rule-no-doubled-joshi
- 文中に連続して出現する助詞に関するルール
- 入れるかどうか のような か について省くように設定しました

参考: ルール一覧

textlint-rule-preset-ja-spacing

textlint-rule-preset-ja-spacing は日本語周りにおけるスペースの有無を決定する textlint ルールプリセットです。

textlint-rule-ja-space-between-half-and-full-width
- 半角文字と全角文字の間にスペースを入れるかどうか
- "space": "always" として設定しスペースを挿入するようにしました
textlint-rule-ja-space-around-code
- インラインコードの周りにスペースを入れるかどうか
- "before": true, "after": true として前後にスペースを設けるようにしました

参考: ルール一覧

VS Code の設定

textlint コマンドを使用してチェックする方法もありますが、VSCode で編集しながらチェックできた方が便利です。エクステンションのvscode-textlint - Visual Studio Marketplace を導入するとすぐに利用可能になります。

細かい設定はあるようですが、デフォルト設定でも問題なく使えています。