このブログでは markdownlint を使ったチェックを回してから記事を更新するようにしています。今日はその設定例を紹介したいと思います。

markdownlintについて

DavidAnson/markdownlint: A Node.js style checker and lint tool for Markdown/CommonMark files.

markdownlint is a static analysis tool for Node.js with a library of rules to enforce standards and consistency for Markdown files. It was inspired by - and heavily influenced by - Mark Harrison’s markdownlint for Ruby. The initial rules, rule documentation, and test cases came directly from that project.

名前のとおり Markdown のリンターです。Visual Studio Code の拡張機能でちょっと有名なやつです。

lint【linter】

読み方：リント
lint 【linter】
lintとは、コンピュータプログラムなどのソースコードを読み込んで内容を分析し、問題点を指摘してくれる静的解析ツール。また、そのようなツールで解析を行うこと。ツールを指す場合は “linter” （リンター）と呼ぶこともある。

大前提として、このブログを生成している Hexo では記事は全て Markdown で書いています。なので、記事のファイルに対して Linter によるチェックを行おうというものです。

ウチのブログでは markdownlint のCLIツールである markdownlint-cli をCIに組み込んで、更新のたびにすべての記事をひととおりチェックするようにしています。

markdownlint によるチェックは思ったよりかなり厳密で、全部ガチガチにチェックするとけっこうウザいです。

技術書のようなお堅い文章を書いているわけではなくただの適当な日記なのでそこまでせんでも、というところなのですが軽めに Markdown の記法チェックはしておきたいなーという温度感なので、今日はそんな人向けのゆるめな設定例を紹介してみたいと思います。

インストール

公式みてくれ、で済む話ですが、npm でインストールするだけです。

npm install -g markdownlint-cli

設定例

VSCode の拡張機能である markdownlint でも、CLIツールの markdownlint-cli でも設定内容に関しては共通なので多少の参考にはなると思います。
markdownlint-cli では .markdownlint.yml に無効する設定項目を記載します。ウチでは以下の設定を無効にしています。日本語でコメントつけているので無効にしている設定の内容はコメントを見てください。逆にチェックを行いたい項目については .markdownlint.yml に記載しなければチェックされます。

.markdownlint.yml

# Docs
# https://github.com/DavidAnson/markdownlint/blob/a852407c887ec60949aa5365ed964bab833f962f/doc/Rules.md

# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
# チェック不要。そのうちデフォルトで false になるらしいがバージョンによるのでとりあえず明示的に設定
MD002: false

# MD012/no-multiple-blanks - Multiple consecutive blank lines
# 2行以上の空行があるとコケる。これも表示に影響はないのでスルーする。
MD012: false

# MD013/line-length - Line length
# 1行の表示上限チェックは不要。
MD013: false

# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
# ヘディングの上下にスペースがないとエラーになる。Hexoでの表示に影響ないのでそこまでチェックしない。
MD022: false

# MD026/no-trailing-punctuation - Trailing punctuation in heading
# 見出しに句読点があっても別に構わないのでfalse
MD026:

# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
# コードブロックの上下に空白行がないと怒られます。特にウチでは表示に影響ないのでチェックしない
MD031: false

# MD033/no-inline-html - Inline HTML
# インラインHTMLは許可するのでfalse
MD033: false

# MD034/no-bare-urls - Bare URL used
# ハイパーリンクに変換されて困るURLは自分でエスケープ済みなのでここではチェック不要
# 入れたい人は入れても良い
MD034: false

# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
# 見出しのかわりに強調表示を使うと怒られる
# ただ、見出しを使いたくない場合もあるのでチェックしない
MD036: 

# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
# ウチではh1はサイト名に使われているのでチェックしない
MD041: false

# MD043/required-headings/required-headers - Required heading structure
# 見出しの構造なんて記事によって変わるのでチェックしない
MD043: false

ちなみに全ての設定項目についてはこちらを参考にしてください。
markdownlint/Rules - DavidAnson/markdownlint

CIへの導入

ここで markdownlint の実行を行なっています。

サイトのビルドをGitHub Actionsで行うように変えました | Jpsern.com

抜粋内容

jobs: # デプロイの前にテストを実行 # これがコケた場合デプロイは行われない test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 # 前述で作成したアクションをここで呼んでいます - name: Setup Node.js and Yarn uses: ./.github/actions/setup - name: Markdownlint run: yarn run mdlint

感想

たかだか個人のブログでそこまでやらなくてもいいような気はします
好奇心でやってみたい人は参考にしてみてください。

ちなみに

この記事を追加した際に 記法エラーでmarkdownlintに怒られました。 (実話)