Markdown+VSCodeでブログを執筆する環境を整えてみた

2022年10月21日 09:46

はじめに

こんにちは、SHIFTのITソリューション部に所属しているHoribeです。現在は開発支援プロダクト推進部に出張し、テックブースト研修という技術研修に参加しています。

テックブースト研修では主に開発の基礎について学んでおり、その一環として学んだことを技術ブログにアウトプットしたいと思いました。エンジニアはよくMarkdownを使って技術ブログを書いていることを知り、Markdownの書き方を習得していざ書き始めたのですが、雑に書いてしまうと思っていたより修正が必要です。かと言ってMarkdownの正しい記法や改行の調整などに気を配りながら書くと、内容の推敲に没頭できず非効率に感じました。

そこで、Markdownの記法に沿った記述の補助をしてくれて、保存するたびに整形してくれる仕組みを作れないかと考えたのが本記事を書いたきっかけです。紆余曲折の末にこれなら快適だと思える環境を整備できたので、その手順を備忘録としてまとめます。

この記事の目的とポイント

目的は、ストレスなくMarkdownでブログを執筆できる環境を作ることです。具体的な要件としては、Markdown記法の補助をしてくれること、Ctrl+Sを押下したときにMarkdownのフォーマットを自動で整形して保存させることの2つになります。

前者にはMarkdown All in One、後者にはPrettierという拡張機能を使います。Markdown All in Oneは、Markdown記法の自動補完機能などを追加してくれます。PrettierはNode.js上で利用できる人気のコードフォーマッターで、HTMLやJavaScriptなどに加えてMarkdownにも対応しています。非常に使い勝手のいいパッケージですが、日本語の文章を整形させようとすると一つ問題が起こります。日本語と英数字が混じった文章に対してフォーマットを走らせると、英数字の前後に半角スペースを挿入してしまう問題です。

犬はdogで猫はcatでペンギンはpenguinです。それぞれ2匹います。 // フォーマット前
犬は dog で猫は cat でペンギンは penguin です。それぞれ 2 匹います。 // フォーマット後

これでは日本語の文章として明らかに不自然ですね。半角スペースを逐一手動で消していくのは、途方もない作業になることが想像できます。本記事のポイントは、プラグインを使ってこの問題を回避することです。

手順

前提

VSCodeがインストールされていること、Node.jsの実行環境がありnpm(またはyarn)が利用できることです。
OSの制約は特にありません。

1. ドキュメントを管理するディレクトリを準備する

まずはドキュメントを管理するディレクトリを適当な場所に作成します。筆者は開発するディレクトリをdevelopとしていたので、執筆するディレクトリということでwriteと名付けました。

2. VSCodeの拡張機能にPrettierをインストールし、デフォルトのフォーマッターに設定する

次はVSCodeの設定です。前述した便利なコードフォーマッターであるPrettierをVSCodeに追加します。アクティビティバーの拡張機能から「Prettier」と検索すればトップに出てくるので、インストールします。
メニューバーからファイル>ユーザー設定>設定と進むとEditor: Default Formatterという項目が出てくるので、Prettier - Code formatterを選択します。
setting.jsonに"editor.defaultFormatter": "esbenp.prettier-vscode"を追記するやり方でも可能です。

(ちなみに設定画面はCtrl+,でも開くことができます。)

3. VSCodeの設定でFormat On Saveにチェックを入れる

もう一つPrettierに関する設定です。Ctrl+Sで変更を保存した際、自動でフォーマットが走るように設定します。

メニューバーからファイル>ユーザー設定>設定と進むとEditor: Format On Saveという項目が出てくるので、チェックを入れておきます。

手順2と同じく、setting.jsonに"editor.formatOnSave": trueを追記するやり方でも可能です。

これでファイルを保存する度に自動でPrettierがフォーマットしてくれます。

4. VSCodeの拡張機能にMarkdown All in Oneをインストールする

これはMarkdownでの執筆を補助してくれる拡張機能です。これも同じく、アクティビティバーの拡張機能から「Markdown All in One」と検索すればトップに出てくるので、インストールします。

太字や斜体、見出しレベルの変更などのショートカットキー機能や、箇条書き・番号付きリストの自動補完をしてくれます。使い慣れると非常に便利なので、まだMarkdownがよくわからない人は初めからMarkdown All in Oneありきで学習してみるのもよいと思います。

5. npmでPrettierをインストールする

npmを使ってPrettierのパッケージをインストールします。
まずはnpmを使うためにディレクトリを初期化します。次のコマンドで初期化できます。

$ npm init

次に準備したディレクトリに移動して、Prettierをインストールします。

$ npm install -D prettier

これでPrettierの導入はできました。しかし、このままでは前述したように日本語とアルファベットの間に半角スペースが入ってしまい、不便です。

6. npmでprettier-plugin-md-nocjspをインストールして設定する

最後に半角スペースが挿入される問題を解決します。ありがたいことに、同じ悩みを持った方が対策用のプラグインを既に開発してくれています。「prettier-plugin-md-nocjsp」というプラグインです。こちらをインストールします。

$ npm install -D prettier-plugin-md-nocjsp

インストールできたら、Prettierにこのプラグインを噛ませる設定を記述します。
ディレクトリルートに.prettierrcファイルを作成し、以下のコードを記述して保存してください。

{
  "overrides": [
    {
      "files": ["*.md", "README"],
      "options": {
        "parser": "markdown-nocjsp"
      }
    },
    {
      "files": "*.mdx",
      "options": {
        "parser": "mdx-nocjsp"
      }
    }
  ]
}

これで完成です！

まとめ

以上の手順で、Markdown記法の補助をしてくれて、保存と同時にMarkdownのフォーマットを整形してくれる環境を構築できました。番号付きリストを書く際にいちいち数字を考えて入力する必要がなくなったり、見出しの上下には改行を入れてくれたり、細かな記法を意識せずにMarkdownで文章が書けるようになります。

ブログのように時間をかけて文章を考える場合はもちろん、人の話をメモするときなどスピードが求められる場合にも有効です。最低限の記法さえ守れば、雑に書いても情報構造に従って整形してくれます。

一方で、誤った記法で書いてしまったときにエラー警告のような表示が出る機能があれば、更にMarkdownでの執筆が捗ると思いました。

おわりに

今回の記事では、Markdownで快適にブログを執筆する環境の構築手順をまとめました。Markdownは、文章の情報構造を簡単に表現できる優れたマークアップ言語だと思います。この記事がMarkdownユーザーの一助になれば幸いです。筆者自身も、技術ブログに限らず様々な内容を本環境を通じてアウトプットしていきたいと思います。

執筆者プロフィール: Rintaro Horibe
ITソリューション部に所属。現在は開発支援プロダクト推進部で行われているテックブースト研修に参加中。
マイブームはポーカーと散歩。

お問合せはお気軽に
https://service.shiftinc.jp/contact/

SHIFTについて（コーポレートサイト）
https://www.shiftinc.jp/

SHIFTのサービスについて（サービスサイト）
https://service.shiftinc.jp/

SHIFTの導入事例
https://service.shiftinc.jp/case/

お役立ち資料はこちら
https://service.shiftinc.jp/resources/

SHIFTの採用情報はこちら
https://recruit.shiftinc.jp/career/

最後まで読んでくださり、ありがとうございます！

御社サービスのご相談はお気軽に。

ソフトウェア品質のプロがお伺いします。