textlintとVSCodeを使って記事を書く

この記事は PharmaX Advent Calendar 2022 4日目 の記事です。

---

最近フロントエンドのコードを書くことがあり、VSCodeでコーディングしていた。
そのプロジェクトはHuskyを使ってコミット前にチェックが走るようにもなっていたので、それに依存する色々な拡張機能をVSCodeにインストールしたところ、いつの日からか英字の前後に半角スペースが入るようになった。
例）テスト TEST テスト

この原因を調べているうちに面白いことが分かってきたので今回はそれがネタ。
このブログの内容をVSCodeを使って記事を書くときやドキュメント書くときに実践してもらうと、事前にある程度チェックされた状態で校閲レビューに回せるので、効率もあがるのではないだろうか。

半角スペースが入る原因はPrettier

主題でネタバレしているが、英字前後に半角スペースが入ってしまうのは prettier だった。
Prettierをローカルなりグローバルなりにインストールし、VSCodeで「Format On Save」をONにしてると勝手にフォーマッターがいい感じにファイルをフォーマットしてくれる。これはPrettierだけではなく、Linterでも同じ。（例えばJSのstylelintやeslintも）
今回は特定のリポジトリに対してだけでなくVSCodeを使って編集するさまざまなファイルを勝手にlintしてくれる状態となっていたのである。
そういえばVSCode起動時に「.prettierrcファイルがないよ」という警告出てた気がしてきた……。

根本原因は別にあった

とはいえlintをかけてくれる事自体は全然問題ないしむしろありがたいのだが、VSCodeのPrettierの設定欄をみても一切この半角スペースを排除するための設定が存在しない。
ちょっと検索すると以下の記事が引っかかった。

和欧文字間（漢字仮名と英数字の間）に半角スペースが挿入されないようにするPrettier Markdownプラグインを作った - Qiita

つまりPrettierの内部コードでとりあえず英字は前後に半角スペース勝手に入れるのが強制仕様だったのである。そしてそのIssueは2年ほど放置されていたという事実もまた判明。

上記のQiita記事作成者の作った対象PRがこれ。
https://github.com/prettier/prettier/pull/11597

よく見るとなんと merge されているではないか。バージョンを確認するとどうも 3.0.0-alpha.3 のようだった。（changelogを参照）
ということは、このバージョンのPrettierを使えば解消するはずなのでやってみることにした。

別途分かったことだが、VSCodeの拡張機能であるPrettierをインストールすると、ローカルに依存するprettierがない場合は、勝手に拡張機能内のprettierを使うらしい。
これを回避するために "prettier.resolveGlobalModules": true を設定するとよい。ただしこの設定はグローバルにインストールされているPrettierも参照しにいくため、幅広く影響を及ぼすことに注意。

早速やってみよう（2022/11/14時点の最新はalpha4）

npm install -g npm install -g prettier@3.0.0-alpha.4

VSCodeのsettings.jsonは以下のように設定。こちらは個別のWorkspaceやRepository単位で、.vscodeディレクトリ配下に作成するのを推奨する。

{
  "prettier.resolveGlobalModules": true,
  "textlint.autoFixOnSave": true
}

これで準備OK。あとはVSCodeを再起動。

さらにtextlintを適用してより統一性を確保する

日本語ドキュメントを書く人向けに便利な国産ツールとして textlint がある。
このNode.jsのパッケージツールとVSCode拡張機能のtexlintを組み合わせて使うことで日本語文章を効率よく統一性を担保した状態で記述することができる。
textlintそのものにはルールが存在せず単体では効果を発揮しないので、用途に応じてルールセットを別途インストールする必要がある。
ルールセットには以下のようなものがある。

• textlint-rule-preset-JTF-style
  JTF日本語標準スタイルガイドに則った文書の添削をしてくれるルール
• textlint-rule-preset-ja-technical-writing
  技術文書向けのルールで割と厳しめなので↓で紹介するtextlint-filter-rule-allowlistと組み合わせて使うのが推奨
• textlint-filter-rule-allowlist
  許容する単語を追加することでlint対象外にできるルール

グローバルインストールする場合は以下。

npm install -g textlint textlint-rule-preset-ja-technical-writin textlint-filter-rule-allowlist

その後、実際にtextlintの挙動を設定するために.textlintrcというファイルに色々と書く。
例えばこんな感じ。

{
  "filters": {
    "whitelist": {
      "allow": [
        "てすと単語",
        "拝承"
      ]
    }
  },
  "rules": {
    "preset-ja-technical-writing": {
      "max": 120,
      "no-mix-dearu-desumasu": false
    }
  }
}

参考： Asciidocで仕様書の「開発環境」を整える (1) - Qiita

なお、上記ルールのみでは日本語文章でよく発生する「表現揺れ（コンピューター、コンピュータ、PCなど）」には対応できない。表現揺れ対応には以下のSansan社のブログがとても参考になると思うので真似してルールを自作しよう。
参考： textlintによる表記ゆれ撲滅 - Sansan Tech Blog

ドキュメントを書こう

ここまで読んでもらうときっと手元には様々なドキュメントをVSCodeで静的解析できるようにするための基盤は整ったのではないかと思う。しかし、大事なのは基盤整備ではなく、それを使って何をやるかである。今回の場合はドキュメントを書くということがやるべきことだ。

個人的に技術文書を書くのが僕自身も苦手で、新人の頃から中堅になるまで永遠と上司から「てにをは」やその他文書構成について指摘され続けてきた。そういう歴史もあって、少なくとも「かなぁ？」とか「かも？」みたいな文末表現を見るとムズムズするのだが、当時の会社から離れて時間がだいぶ経つ今ではむしろ自分も社内でのみ共有される内部資料や自分メモみたいなものには、砕けた表現を使う機会も増えてきた。
とはいえ、そういう作法がクセになるといざというときに問題が起きるのは自明なので、なるべく文書表現は組織内で統一するに越したことはない。だが、これを人手でやるにはレビューする側もされる側も結構な労力を要してしまう。

ではどうやったらドキュメントが書けるようになるか、答えは簡単だ。とにかく書くである。

「絵が上手くなるには」=とにかく描く！
「サッカーが上手くなるには」=とにかく練習！
「プログラミングが上手くなるには」=とにかく書く！

共通して言えることは、圧倒的に最初は質より量。
量をこなす間に質は自ずと上がってくるものだ。そしてこの質を最初から一定水準にできるものこそ今回のtextlintの基盤である。是非活用して量をこなし、ドキュメントの書けるエンジニアへと成長してほしい。
（なお、なぜドキュメントを書く必要があるのかは割愛する）