Lintで整えるZenn執筆環境

はじめに

ZennではZenn CLIとGitHubとのリポジトリ連携を使うことで、使い慣れたエディタで記事をプレビューしながら快適に執筆できます。

ただし、長く書いていると文体や表記の揺れが気になることもあります。
そこで今回は、markdownlintとtextlintを導入し、より整った形で書けるようにする方法を紹介します。

なお、Zenn CLIやリポジトリ連携機能の使い方については公式の記事があるためここでは割愛します。

https://zenn.dev/zenn/articles/install-zenn-cli

https://zenn.dev/zenn/articles/connect-to-github

今回使用したツールのバージョンは下記のとおりです。

ツール	バージョン
markdownlint	0.39.0
textlint	15.2.3
textlint-rule-preset-ja-technical-writing	12.0.2

markdownlintの導入

markdownlintとは

markdownlintは、Markdown文書のスタイルを自動でチェックしてくれるLintツールです。
例えば見出しの階層や、改行・空行の有無、リストやコードブロックの書き方などをルールに基づいて検出し、統一されたドキュメントを書くのを助けてくれます。

導入方法

導入は下記のコマンドで行えます。

npm install -D markdownlint

エディタとの連携

markdownlintには各種エディタ向けの拡張機能が存在し、エディタ上でLint結果をリアルタイムに確認・修正しながら執筆できます。

エディタ	拡張機能リンク
VS Code	markdownlint
Sublime Text	SublimeLinter-contrib-markdownlint
Vim/Neovim	coc-markdownlint
Emacs	flymake-markdownlint-cli2

.vscode/settings.json

{
  "editor.formatOnSave": true,
  "[markdown]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
  }
}

VS Codeの場合は上記の設定で、ファイルの保存時に自動修正可能なのもについては修正されます。
"editor.formatOnSave": true にすることで、ファイルを保存したタイミングで自動的にフォーマッターが実行され、対応可能な修正が自動で反映されます。
例えば余分な空白の除去や、ルール違反の修正などが自動で行われるため、手作業の負担が減ります。

なお、markdownlintをCLIで実行したい場合はmarkdownlint-cli2を使用します。

ルールの設定

markdownlintは、デフォルトではすべてのルールが有効になっています。
しかし、Zennの記事執筆では、初期設定のままだと少し書きづらく感じる場面があるため、用途に合わせてルールをカスタマイズするのがおすすめです。

プロジェクトのルートディレクトリに.markdownlint.jsonを設定することで各ルールのカスタマイズを行うことができます。

.markdownlint.json

{
  "MD013": false,
  "MD024": {
    "siblings_only": true
  },
  "MD034": false,
}

MD013

1行あたりの最大文字数を制限するルールです。
英語では可読性向上のために有効ですが、日本語では改行位置を気にせず書きたい場合もあるため、Zenn執筆では無効化しておくと書きやすくなります。

MD024

同一ドキュメント内で同じ見出し名を複数回使うことを禁止するルールです。
siblings_onlyをtrueにすることで、異なる階層（親見出し）の中で同名見出しを許可できます。
Zennの記事では同じ構造を繰り返す場合もあるため、この設定を有効にしておくと便利です。

MD034

URLを記載する際に、山括弧で囲むことを強制するルールです。

❌ Bad
https://zenn.dev/zenn/articles/install-zenn-cli

✅ Good
<https://zenn.dev/zenn/articles/install-zenn-cli>

ZennではURLをそのまま記載した場合はリンクカードとして表示され、<>で囲った場合はリンク化されたURLとして表示されます。
そのため、このルールを無効にすることでリンクカードでの表示を行えるようにします。

リンクカード

リンク化されたURL

textlint

textlintとは

textlintは、自然言語向けのLintツールです。
文体の統一や誤字脱字、助詞の使い方などをチェックしてくれます。
社内のテックブログなどでは、「です・ます調」で統一するなど文体ルールが定められている場合もあり、textlintを使うことでそのようなルールにも対応しやすくなります。
今回はtextlint-rule-preset-ja-technical-writingを使用し、技術文書向けのチェックを行います。

導入方法

textlintと使用する校正ルールをインストールします。

npm install -D textlint textlint-rule-preset-ja-technical-writing

ルールの設定

.textlintrc.jsonでルールを有効化します。

.textlintrc.json

{
  "rules": {
    "preset-ja-technical-writing": true
  }
}

実際にLintを行うと、ルールが正常に動作していることが確認できます。

❯ textlint **/*.md

/Users/xxx/xxx.md
  128:27  error  【dict5】 "設定を行う"は冗長な表現です。"設定する"など簡潔な表現にすると文章が明瞭になります。
解説: https://github.com/textlint-ja/textlint-rule-ja-no-redundant-expression#dict5  ja-technical-writing/ja-no-redundant-expression
  140:6   error  本文: "ですます"調 でなければなりません
=> "ですます"調 であるべき箇所に、次の "である"調 の箇所があります: "である。"
Total:
である  : 1
ですます: 28
                  no-mix-dearu-desumasu

✖ 2 problems (2 errors, 0 warnings, 0 infos)

また、textlintにはVS Codeの拡張機能があるため、インストールするとエディタ上で確認できるようになります。

おわりに

Lintツールを導入しておくと、執筆のたびに細かい文法やスタイルを気にせず、内容に集中できます。
ぜひ、自分に合った設定で快適なZenn執筆環境を整えてみてください。