zenn 執筆に markdownlint を導入した
markdownlint is 何
lint と名が付いている通り markdown 用の静的解析ツールです。
いくつかのルールに則り構文チェックしてくれます。
プログラムを書くときは割と当たり前のように入っているので知らずにお世話になっている方もいると思います。
私は普段、markdown で書く時って特に気にせず適当に書いています。
例えば、markdownlint では 「#」 は文の書き出しの１行目にしか書くことができないといったルールがあります。
知らなかったし、個人で書いているだけならルールなんて無視無視とも思っていました。
もちろん、このルールを守らずに書いてもエラーを起こしたりすることもないです。
しかし、綺麗に書くという点において導入する価値はあるかなと考えます。
ルール一覧はこちら
（2023/05 現在 53 個もあるんですねぇ。。。）
なんで導入しようと思ったのか
たまたま目に入っただけです。
markdown を楽に綺麗に書く方法ないかなぁと思いながら VSCode の Extention で markdown と入力したら出てきたので試しに入れてみたのがきっかけです。
入れたら入れたで、今まで書いていたものが黄色だらけになって「私の markdown クソすぎ！？」ってなりました。
私の執筆環境
- zenn-cli を使ったローカル環境
- github でリポジトリを管理
なので、今回は VSCode と commit 時に linter によるチェックを行うようにします。
やりたいことと導入したもの
やりたいこと
- VSCode 上でルールに則さない書き方をしたときに黄色くなる
- github に commit するときに lint でチェックが入る
導入したもの
- VSCode Extention markdownlint
- husky
- lint-staged
- markdownlint-cli2
1. VSCode 上でルールに則さない書き方をしたときに黄色くなる
VSCode Extention から markdownlint をインストールする。
markdownlint と検索蘭に入れれば一番上に出てきます。Marketplace URL
インストールしてから markdown ファイルを見てみるとチェック（黄色く波線が出る）されていることがわかります。
ただし、このままだとルールが厳しすぎるため下記２つをルールから外しました緩和しました。
- MD025/single-title/single-h1: Multiple top-level headings in the same document
- 見出しレベル 1 は 1 つだけというルール
- MD034/no-bare-urls: Bare URL used
- リンクしたい URL は 「<>」 で囲まなければならない
MD025：HTML 観点から見ても h1 が１つしかダメというのはない（と記憶している）ため無効にしました。
とはいえ、Zenn の Markdown 記法一覧のページを見ると、
「アクセシビリティの観点から見出し 2 から始めることをおすすめします」とも書いてあるため、有効のままでもいいかもという気持ちも少しある。
MD034：zenn では URL だけが貼り付けられた行があると、その部分がカードとして表示されます。@[card](URL) という書き方でもカードとして表示されますが楽したいので無効にしました。
↓ こういうやつです
ルールの個別カスタマイズする設定ファイルは json, yaml, cjs などで作成可能ですが、ここでは jsonc で作ることで反映させる方法を紹介します。
この設定は後述する markdownlint-cli2 でも参照するためファイル名もそれに則ったものにしています。
-
.markdownlint-cli2.jsoncを作成 - 下記のように value: boolean の形で個別に無効にしたいルールを追加していきます。
詳しく知りたい方はこちらをチェック -> README
{
"config": {
"MD025": false,
"MD034": false
}
}
2. github に commit するときに lint でチェックが入る
- husky
- lint-staged
- markdownlint-cli2
これらを設定し、自動的にチェックされるようにします。
2-1. husky
git hook は husky を使います。
pre-commit, simple-git-hooks 等でもできると思いますが使ったことある husky を使います。
2-2. lint-staged
コミットされた時にファイルを lint するためこちらを使います。
2-3. markdownlint-cli2
markdown のコマンドライン用 linter です。
無印のものもあり、よく利用されているものです。
markdownlint-cli2 の Overview を見ると、より使いやすくなったもののようです。
VSCode Extention markdownlint とセットで使うことを考えて作られていたり、シンプルかつ速度向上がなされているようです。
3. 設定
3-1. インストール
yarn など別のパッケージマネージャーを使っている方は読み替えてください。
npm i -D lint-staged husky markdownlint-cli2
3-2. lint-staged の設定
コミット時に実行する内容を設定します。
今回は markdownlint-cli2 を md ファイルに対して実行するようにします。
article, books のディレクトリに対してチェックを行えれば OK です。
ですが、ディレクトリを再帰的にチェックしたいのでおまじない的に **/*.md としておきます。
json 等で設定することもできますが、数行なので package.json に追加します。
対象：実行スクリプト となっています。
場所はどこでも大丈夫だと思いますが、私は一番下に追記しました。
{
〜略〜
"lint-staged": {
"**/*.md": "markdownlint-cli2"
}
}
3-3. husky の設定
husky の README を参考に設定していきます。
script を実行して設定をしていきます。
'npx lint-staged' というのはコミット時に 3-2 で追加した lint-staged を実行するということになります。
npm pkg set scripts.prepare="husky install"
npm run prepare
npx husky add .husky/pre-commit "npx lint-staged"
3-4. markdownlint-cli2 の設定
3-２. lint-staged の設定 で markdownlint-cli2 の対象を設定しました。
このままだと、cli を実行したとき node_modules 等の配下にある md ファイルも対象にされてしまうので、対象にして欲しくないディレクトリを指定します。
.markdownlint-cli2.jsonc に以下のように ignores を追加します。
私はこの 3 種類を設定しましたが、必要に応じて追加削除をしてみてください。
{
"config": {
"MD025": false,
"MD034": false
},
"ignores": [".git", "node_modules", ".hasky"]
}
4. 設定が効いているか確認
チェックに引っかかるようにファイルを変更してコミットしてみると。。。
画像のようにエラーが出ました！！
終わりに
これで綺麗なマークダウンを保っていけるように努力できそうです。
あと、textlint, Code Spell Checker の導入することや、有効無効するルールの見直しを行って、より良い形を見つけられたらなと思います。
husky, lint-staged を使ったやり方は他の linter に対しても適用できます。
言語に対して導入していくことでバグの発見やフォーマットが統一されレビューがしやすくなったりとメリットが多いです。
みなさんも導入してみるのはいかがでしょうか？
Discussion
非常に参考になり私も導入する事ができました。ありがとうございます。
一点、気になったことが
とありますがWebページにおいて、見出しのH1はタイトルのみで利用されるものらしいです。
ですのでZenn の記法一覧にある通り、H2から始めた方が良いと思います。
詳しくはわかりませんが、SEOなどの観点からもH2から始めた方が良いらしく、
おそらく検索エンジンでの掲載順位などにも影響があるのかもしれません。
参考情報：https://zenn.dev/neet/articles/f25abb616ec105
すごく役立つことありがとうございます！！
普段は、CMS経由でHTML埋め込むことが多くて、その結果、H1が複数あっても気にならない環境にいました。
すごく納得しますし、勉強になります。
記事の方も頂いた内容をもとに修正させていただきます！