「markdownlint」を使ってMarkdown記法の構文チェックを行う(Vimのaleプラグインと組み合わせるともっと便利に)
はじめに
手に馴染むエディタを使いコードを書きながら、同じぐらいドキュメントを書いてます。
アプリケーションの概要、報告書、ブログからメールに至るまで、最近はMarkdown形式で記載してそれぞれのビューアあるいはコンバータで変換して文字を起こすことが多くなっています。
Markdown記法を利用することのメリット
- 執筆効率がよい
- HTMLのようにタグを書かなくて良いためタイピング量が減る
- 簡単なメモでも早く綺麗に書ける
- 統一したドキュメント形式を保てる
- 汎用性が高い
- 関連ツールや利用できるサービスが多い
- 段落など見た目が統一される
h1
/h2
/h3
/pre
/li
/bold
...
Markdown記法は自由が多い
Markdown記法の習得は非常に容易です。
実際僕も一日ほど使ったぐらいで移行することができました。
理由の一つとして規約の少なさがあげられます。
Markdown記法は自由度を構文チェックで補う
自由度が高いがゆえに、統一感のないドキュメントが出来上がりがちです。
例えばHTMLの文書構造として、 h1
タグの次には h2
タグが登場するべきであり、 h3
タグが登場してはおかしいですね。
同様に #
でタイトルを記載したあとに ###
タイトルが来るとおかしいわけです。 #
タイトルがないというのもやはり同様におかしいですね。
自由度の高いMarkdown記法ですが、
構文チェックを行うことで、弱点を補うことができます。
Markdown記法の構文チェックツール「markdownlint」を使う
僕は 「markdownlint」 というLintツールを利用しています。
導入手順
事前準備
Node.js製のツールとして提供されているため、Node.jsのインストールが必要です。
以下のエントリを参照すればすぐにインストールが可能です。
markdownlintのインストール
npm
コマンドでインストールします。
セットアップは以上になります。
使ってみる
以下のコマンドで実行できます。
$ markdownlint <対象となるmdファイル>
※「nvm」を使ってNode.jsをインストールした手順を利用したため、markdownlintコマンドのインストールパスは以下のようになりました。
※Node.jsのインストールの仕方で変わりますのでご注意ください。
適当なMarkdownファイルを作成し、構文チェックをしてみます。
コマンドを実行しチェックを行います。
大量にエラーが出てきました。
こちらをメッセージどおりに修正し、再度チェックを行います。
$ markdownlint test.md
エラーが表示されなくなりました。
ひとこと
僕はVimでMarkdownファイルを編集しているときに自動的に構文チェックが行われるようにしています。
markdownlint をインストールした上で、Vimの w0rp/ale というプラグインをインストールすれば環境構築は完了です。
ディスカッション
コメント一覧
まだ、コメントがありません