こんにちは、全力開発部の @konoka-iori です。
今回からしばらくの間、「全力開発ブログの作り方」シリーズの記事を投稿します。
このシリーズでは、
- メンバーがどのようにして全力開発ブログに記事を投稿しているか
- 記事を投稿するにあたって、守るべきルールやコーディング規約にはどんなものがあるのか
- 全力開発ブログのリポジトリの構成や運用方法はどのようなものか
- 全力開発ブログのカスタマイズについて
など、全力開発ブログの裏側についてご紹介いたします。
今回の記事では、全力開発ブログで導入されているlintツールについてご紹介します。
以前の記事では、WordPressからHugoに移行した経緯などをご紹介しました。ぜひこちらもご覧ください。
textlint導入までの道
textlintは、主にMarkdownファイルに対してルールベースでテキストをチェックするlintツールです。
全力開発ブログでは、誤字脱字や表記揺れなどをチェックするためにtextlintを導入しています。
きっかけ
執筆環境の更新に伴い、Markdownで記事を執筆することができるようになりました。
VS Codeなど馴染みのあるエディターを使って執筆できる一方で、誤字脱字のチェックがしにくく、結果的に誤字脱字や表記揺れが増えてしまいました。
このままレビュー工程に入ると修正箇所が多くなり、レビューにかかる時間が増えて執筆者もレビュアーも負担が増えてしまいます。
そこで、執筆段階で誤字脱字や表記揺れを機械的にチェックできるtextlintを導入することにしました。
Node.jsの壁。拡張機能で代用
textlintによる自動チェックを行いたいと思いつつも、当初は執筆環境がしっかり統一されておらず、各自がリポジトリをクローンしてローカル環境で執筆していたため、Node.jsが必要なtextlintを導入することは難しいと考えました。
そこで、VS Codeの拡張機能として提供されている テキスト校正くん を使うことで、Node.jsを使わずにある程度のチェックを行うことができるようになりました。
開発元による「テキスト校正くん」の紹介記事はこちらです。 素晴らしい拡張機能をありがとうございます!
カスタム辞書を追加したい
「テキスト校正くん」は、VS Codeの拡張機能として気軽に導入できる一方で、カスタムルールの適用が難しいというデメリットもあります。
僭越ながら「テキスト校正くん」のディレクトリ構造を調べたところ、内部の辞書ファイルを直接編集することで拡張機能に内蔵されている辞書をカスタマイズできることがわかりました。
しかし、仮に内部ファイルを編集して辞書をカスタマイズできても、その設定情報をチーム内で共有・統一することは非常に困難です。
やはり、textlintを導入してカスタム辞書を適用することが望ましいと考え、Dev Containerで環境を統一することにしました。
Dev Containerでtextlintを導入
textlintを導入すべく、Dev Containerでチーム内の執筆環境を統一することにしました。
Dev Containerを利用することで、これまで .vscode
ディレクトリで管理していた設定ファイルや拡張機能を、執筆環境に自動で適用することができるようになり、またメンバーのローカル環境を美しく保つことができるようになりました。
Dev Containerを導入した話は以下の記事で詳しく紹介しています。
導入手順としては以下の通りです。
- カスタム辞書を作成
devcontainer.json
でベースイメージにNode.jsを指定- vscode-textlint
を
devcontainer.json
に追加 npm install
でカスタム辞書をインストールするようdevcontainer.json
に追加"textlint.configPath"
および"textlint.nodePath"
をdevcontainer.json
に追加devcontainer.json
を使ってコンテナーをビルド
カスタム辞書の作成
あくまで「テキスト校正くんにカスタムルールを追加したい」という動機であるため、辞書は テキスト校正くんで採用されているものをベースにさせていただき、 最新の技術用語や過去のレビューで指摘された誤字脱字・表記揺れなどを追加したものを作成しました。
全力開発ブログで採用しているカスタム辞書は以下のリポジトリで公開しています。
textlintを使って良かったこと
導入のメリットとしては、やはりレビュー工程の自動化・効率化です。
しかし、textlintはあくまでルールベースのチェックであるため、事前に定義された誤字脱字や表記揺れのチェックは得意ですが、定義されていない誤字脱字や表記揺れは検知できません。
また、日本語の正しさや表現の適切さ、文章の読みやすさなどを機械的に評価することも難しいため、textlintを過信せずしっかり誤字脱字や表記揺れをチェックすることが重要です。
レビューで発見されたものはtextlintのルールに追加することで次回以降は自動で検知されるようになります。
Markdownlint導入までの道
Markdownlintは、Markdownファイルに対してルールベースでテキストをチェックするlintツールです。
HugoはMarkdownファイルを元に静的ページを生成するため、意図したとおりの記事が生成されるよう、Markdownの記述は正確に行う必要があります。
全力開発ブログでは、Markdownlintを導入し、Markdownの記述ルールを統一することでHugoが正確に記事を生成できるようにしています。
カスタムルール
Markdownlintには、デフォルトでいくつかのルールが定義されていますが、全力開発ブログでは以下のカスタムルールを導入しています。
記事投稿現在では、以下のルールを適用しています。
ルール | 説明 |
---|---|
MD013 :無効化 |
1行が長くなっても問題ない。(ただし、なるべく改行等で読みやすくすることが望ましい。) |
MD024 :無効化 |
複数の見出しで同じ文言を使ってもよい。 |
MD025 :無効化 |
同じ見出しレベルは複数使ってもよい。 |
MD041 :無効化 |
最初の行は見出しレベル1でなくてもよい。(むしろ記事中のH1タグ使用は原則禁止。) |
今後も必要に応じてMarkdownlintのカスタムルールを追加していく予定です。
現在、すでに MD013
については有効化すべきか検討中であり、今後変更される可能性があります。
Dev ContainerでMarkdownlintを導入
textlintと同様に、MarkdownlintもDev Containerで導入しています。
こちらはtextlintより簡単に導入できました。 導入手順は以下の通りです。
devcontainer.json
に markdownlint を追加markdownlint.config
にカスタムルールを追加
Markdownlintを使って良かったこと
Markdownlintを導入することで、記事の記述ルールを統一することができました。
これにより、Hugoで静的ページを生成する際に意図しないレイアウト崩れや表示崩れを防ぐことができ、記事の品質を維持することができました。
まとめ
全力開発ブログでは、執筆環境をDev Containerを使って統一し、textlintとMarkdownlintを導入することで執筆段階からチェックを行い、記事の品質を維持しています。
ただ、textlintやMarkdownlintはあくまでルールベースの機械的なチェックでしかありません。
「lintがあるから大丈夫」と過信せず、しっかりとレビュー工程を行って人間の目でチェックすることが重要です。