textlint を導入しました。

文書作成で、表記揺れを指摘されることがありました。
実は今まで書いてきた記事群の記述も結構危険だなぁと薄々思っていたので、textlintを導入することにしました。
うまく使いこなせたら、本業にも持ち込みたいと思っています。

では、本編。

目次

参考

導入

インストールする先のディレクトリに移動して以下を実行します。

1
2
3
4
5
6
7
8
9
# npm 初期化
npm init -y
# textlint 本体インストール
npm install --save-dev textlint
# textlint　本体以外にルールが必要
# 今回は,技術文書向けのtextlintルールプリセット を使用する。
npm install textlint-rule-preset-ja-technical-writing
# textlint を初期化
npx textlint --init

導入したルールは、技術文書向けの textlint ルールプリセットです。

.textlintrc を開くと以下のようにpreset-ja-technical-writingが適用された状態になっています。

.textlint
1
2
3
4
5
6
{
  "filters": {},
  "rules": {
    "preset-ja-technical-writing": true
  }
}

試しに、textlint-rule-preset-ja-technical-writingを入れる前に、npx textlint --initを実行してみました。
その時は以下のようになっていました。

.textlint
1
2
3
4
{
  "filters": {},
  "rules": {}
}

ルールをインストールしてからnpx textlint --initしたほうが楽ですね。

実行

以下のコマンドで実行できます。

1
2
3
npx textlint [チェック対象ファイルを含むディレクトリのパス]
# もしくは
npx textlint [チェック対象ファイルのパス]

ルールに引っかかったものがあると、以下のような表示をします。
今回は「、」を一文で 3 回以上使うのはだめだというルールに引っかかりました。

1
2
3
  8:56  error  一つの文で"、"を3つ以上使用しています  ja-technical-writing/max-ten

✖ 1 problem (1 error, 0 warnings)

直すと何も表示せずに終了します。

問題点

今回投稿も、textlint を使っていますがブログ特有の問題が発生しています。
以下の部分が、「1 文の長さは 100 文字以下とする」というルールに引っかかります。

1
導入したルールは、[技術文書向けのtextlintルールプリセット](https://github.com/textlint-ja/(textlint-rule-preset-ja-technical-writing)です。
1
2
  38:1  error  Line 38 sentence length(110) exceeds the maximum sentence length of 100.
Over 10 characters  ja-technical-writing/sentence-length

URL を記述すると長くなりますね・・・。

回避策

textlint-filter-rule-commentsを導入します。
以下を実行します。

1
npm install --save-dev textlint-filter-rule-comments

.textlintrc を以下のように編集します。

.textlint
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "filters": {
    "comments": {
      // enable comment directive
      // if comment has the value, then enable textlint rule
      "enablingComment": "textlint-enable",
      // disable comment directive
      // if comment has the value, then disable textlint rule
      "disablingComment": "textlint-disable"
    }
  },
  "rules": {
    "preset-ja-technical-writing": true
  }
}

textlint-filter-rule-comments を導入したことで、<!-- textlint-disable -->と<!-- textlint-enable -->が使用できます。
以下のようにエラー箇所の記載を修正します。

1
2
3
4
5
<!-- textlint-disable -->

導入したルールは、[技術文書向けの textlint ルールプリセット](https://github.com/textlint-ja/(textlint-rule-preset-ja-technical-writing)です。

<!-- textlint-enable -->

再度チェックすると、エラーが外れます。
仕方がないことですが、多用は避けたいところです。
<!-- textlint-disable -->を使用すると、すべてのチェックをスルーします。
「1 文の長さは 100 文字以下とする」というルールだけスルーするようにしてみます。
エラー時の記述から、ルール定義名はja-technical-writing/sentence-lengthとわかるのでこちらを追加します。

1
2
3
4
5
<!-- textlint-disable ja-technical-writing/sentence-length -->

導入したルールは、[技術文書向けの textlint ルールプリセット](https://github.com/textlint-ja/(textlint-rule-preset-ja-technical-writing)です。

<!-- textlint-enable ja-technical-writing/sentence-length -->

技術文書向けの textlint ルールプリセットでは、パラメータを調整して100文字以上にする方法も載っていますが、全体としては厳しくあってほしいのでこうしました。

もしパラメータ調整するなら、以下のように.textlintrc を書き換えます。

.textlintrc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "filters": {
    "comments": {
      // enable comment directive
      // if comment has the value, then enable textlint rule
      "enablingComment": "textlint-enable",
      // disable comment directive
      // if comment has the value, then disable textlint rule
      "disablingComment": "textlint-disable"
    }
  },
  "rules": {
    "preset-ja-technical-writing": {
      "sentence-length": {max: 130},
    }
  }
}

別のルールを試そう

.textlintrc に記載されていないルールでチェックできます。
今度は、textlint-rule-preset-japaneseを試してみます。

インストールと実行は以下の通り。

1
2
3
4
5
6
7
# 導入
npm install --save-dev textlint-rule-preset-japanese

# 実行
npx textlint [チェック対象ファイルを含むディレクトリのパス] --preset textlint-rule-preset-japanese
# もしくは
npx textlint [チェック対象ファイルのパス] --preset textlint-rule-preset-japanese

今度は、japanese/sentence-length という別の 100 文字制限に引っかかってしまいました。
仕方ないですね・・・。

1
2
3
4
5
6
   38:1  error  Line 38 sentence length(110) exceeds the maximum sentence length of 100.
Over 10 characters   japanese/sentence-length
  142:1  error  Line 142 sentence length(156) exceeds the maximum sentence length of 100.
Over 56 characters  japanese/sentence-length

✖ 2 problems (2 errors, 0 warnings)

プリセット名を覚えておく自信が無いので、.textlintrc を以下のようにしておくことにしました。
標準で使わないものも書いておいて、falseにしておけばいいということで。

.textlintrc
1
2
3
4
5
6
7
8
9
10
11
12
{
  "filters": {
    "comments": {
      "enablingComment": "textlint-enable",
      "disablingComment": "textlint-disable"
    }
  },
  "rules": {
    "preset-ja-technical-writing":true,
    "textlint-rule-preset-japanese":false
  }
}

表記揺れのチェック

textlint-rule-prhを導入します。

インストール配下の通り。

1
npm install --save-dev textlint-rule-prh

.textlintrc を以下のように書き換えます。

.textlintrc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "filters": {
    "comments": {
      // enable comment directive
      // if comment has the value, then enable textlint rule
      "enablingComment": "textlint-enable",
      // disable comment directive
      // if comment has the value, then disable textlint rule
      "disablingComment": "textlint-disable"
    }
  },
  "rules": {
    "preset-ja-technical-writing":true,
    "prh": {
      "rulePaths" :["prh/prh.yml"]
    },
    "textlint-rule-preset-japanese":false
  }
}

prhというディレクトリを作って、prh.ymlを作成します。
prh.ymlの中身はtextlint-rule-prhの記載をそのまま持ってきました。

ベンダと書いたファイルを対象に実行してみます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# チェック実行
npx textlint [チェック対象ファイルのパス]

  244:1  ✓ error  ベンダ => ベンダー              prh

✖ 1 problems (1 errors, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

# 定義に基づいて修正
npx textlint [チェック対象ファイルのパス] --fix
  248:1  ✔   ベンダ => ベンダー  prh

✔ Fixed 1 problem
✖ Remaining 1 problem

以上でチェック対象ファイルのベンダがベンダーに直ります。

textlint-rule-prh用の.yml ファイルを公開している人がたくさんいるようなので、参考にしながらカスタマイズしてみようと思います。

今回は textlint を導入してみました。
textlint で読みやすい記述を目指したいところです。

最後に今まで書いた 56 個の.md ファイルすべてにチェックをかけたら 615 個エラーを出して吐きたくなりました。
順番に直してゆきます。

ではでは。