Visual Studio Code で Markdown 編集環境を整える

最近、新規環境を構築したので忘れないようにメモ。
いまのところVisual Studio Code が最強の Markdown エディタだと個人的には思う。

環境

• Windows 10 Pro (64bit)
• Visual Studio Code 1.28.2

1. Prettier - Code formatter をインストール

拡張機能『Prettier - Code formatter』をインストールします。

Prettier はコードフォーマッターで、Markdown にも対応しています。
インストールするとShift + Alt + Fでドキュメント整形してくれます。

私は設定していないのですが、ファイル保存時に自動的に整形したい場合、ユーザー設定で editor.formatOnSave を True にします。

settings.json

"editor.formatOnSave": true

私が true にしていない理由としては、日本語と英語の間に自動的に半角スペースを入れられるのが好みでないからです。
その詳細は以下の記事に書きました。

PrettierでMarkdownをフォーマットしたときの英語と日本語の間に入るスペースをどうにかする

2. markdownlint をインストール

拡張機能『markdownlint』をインストールします。

markdownlint はその名の通り Markdown の lint ツールです。
インストールすると、よろしくない書き方をビシバシ指摘してくれます。

3. Markdown Checkbox

拡張機能『Markdown Checkbox』をインストールします。

チェックボックス生成コマンドを追加する拡張です。

4. Markdown Preview Enhanced

拡張機能『Markdown Preview Enhanced』をインストールする。

どんな機能があるかについては、公式ドキュメント、他の方の良記事をご参考ください。

【ドキュメントが書きたくなる】Markdown ライブプレビュー + インライン数式/UML/図表 + 綺麗に PDF/Word エクスポートまで
Visual Studio Code + Markdown Preview Enhanced はチームでデファクト化したい Markdown 環境だ！、と思う(2017/10 月時点)

PDF 出力できるようにする

※MPEバージョン0.4.0でphantomjsのサポートが終了となりました。

• Remove phantomjs support. Add chromePath to settings.

残念ですが仕方のないことです（以前はphantomjsをお勧めしていました）

現状、私の環境ではChrome(Puppeteer)でPDFにするとフォントがおかしくなりました。
ですがHTMLに出力すると問題がなかったため、MPEプレビューの右クリックメニューから一度HTMLに変換して
さらにブラウザでPDFプリントをするのをお勧めします。

【補足】
PDF(prince)は無料だと商用不可のため試していません。

plantUML に対応する

Graphviz をインストールします。
https://graphviz.gitlab.io/_pages/Download/Download_windows.html

テーブルの colspan,rowspan に対応

ユーザー設定でmarkdown-preview-enhanced.enableExtendedTableSyntax を trueにすると
テーブルの colspan と rowspan に対応できます。

true にした状態で、下記のコードを貼り付けてプレビュー表示してみてください。

colspan `>` or `empty cell`:
| a   | b   |
| --- | --- |
| >   | 1   |
| 2   |

rowspan `^`:
| a   | b   |
| --- | --- |
| 1   | 2   |
| ^   | 4   |

html 出力時にサイドバー TOC を有効化

※セキュリティリスクがあるので利用の際はご注意ください。
以前はデフォルトで有効でしたが、セキュリティの関係上デフォルトで無効になっています（ver.0.3.5 以降）。
有効にするには、ユーザー設定でmarkdown-preview-enhanced.enableScriptExecutionをtrueにします。

有効にすると、html 出力時にサイドバーメニュー（目次）が生成されます。
ちなみにメニューボタンが左下に表示されるのですが、好みでないので左上にカスタマイズしています。

1. ctrl+shift+p を押し、 Markdown Preview Enhanced: Customize Cssを開きます

2. 以下を最終行の後に追加します。

   style.less

   // サイドバーTOCを左上にする
   .md-sidebar-toc.md-sidebar-toc {
     padding-top: 40px;
   }
   
   #sidebar-toc-btn {
     bottom: unset;
     top: 8px;
   }
   

【解消済み】UNC パス（共有フォルダ）のファイルがプレビューできない

※MPEバージョンv0.5.3で修正されました。
UNCパス（共有フォルダ）のファイルがシングルプレビューモードでプレビュー出来るようになりました。

Markdown Preview Enhanced のv0.5.3より前のバージョンでは、シングルプレビューモードを false にしないと共有フォルダのファイルがプレビューできませんでした。下記のエラーが発生していました。

Running the contributed command:'markdown-preview-enhanced.openPreview' failed.

これを解消するには、ユーザー設定でmarkdown-preview-enhanced.singlePreviewをfalseにします。

settings.json

"markdown-preview-enhanced.singlePreview": false

Markdown Preview Enhanced のテーマ

デフォルトのテーマはgithub-light.cssで、デフォルトを利用しています。

ですが、github と言いつつ、あまり GitHub に似てないような……
近づけるためにh1,h2 の見出しにアンダーラインだけ追加してます。

1. ctrl+shift+p を押し、 Markdown Preview Enhanced: Customize Cssを開きます

2. 以下のようにします

   .markdown-preview.markdown-preview {
     // modify your style here
     // eg: background-color: blue;
     h1,
     h2 {
       border-bottom: 1px solid #eaecef;
     }
   }
   

5. Markdown All in One をインストール

拡張機能『Markdown All in One』をインストールします。

どんな機能があるかについては、公式ドキュメントなどをご参考ください。

キーボードショートカット コマンド markdown.extension.togglePreviewToSide を削除

Markdown All in One はプレビュー表示のショートカットをオーバーライドします。
これは、ctrl+k vでプレビュー表示のトグル（開く,閉じるの切り替え）を行うためですが、Markdown Preview Enhanced（MPE）と競合するため無効にします。
ちなみに、有効状態だと MPE のプレビューではなく、デフォルトのプレビューが表示されます。

1. VS Code のメインメニューから、ファイル ＞ 基本設定 ＞ キーボードショートカットを開きます。
2. ctrl+k vで検索し、コマンド markdown.extension.togglePreviewToSideを右クリックしキーバインドを削除します。

Markdown All in One のユーザー設定

私は以下のようにしています。

"markdown.extension.orderedList.marker": "one",
"markdown.extension.orderedList.autoRenumber": false,
"markdown.extension.syntax.decorations": false,
"markdown.extension.tableFormatter.enabled": false

設定まとめ

settings.json

VS Code ファイル > 基本設定 > 設定（settings.json）

settings.json

{
    "markdown-preview-enhanced.enableExtendedTableSyntax": true,
    "markdown-preview-enhanced.enableScriptExecution": true,
    "markdown-preview-enhanced.previewTheme": "github-light.css",
    "markdown.preview.breaks": true,
    "markdown.extension.orderedList.marker": "one",
    "markdown.extension.orderedList.autoRenumber": false,
    "markdown.extension.syntax.decorations": false,
    "markdown.extension.tableFormatter.enabled": false,
}

Markdown Preview Enhanced: Customize Css

ctrl+shift+p を押し、 Markdown Preview Enhanced: Customize Cssを開く

style.less

/* Please visit the URL below for more information: */
/*   https://shd101wyy.github.io/markdown-preview-enhanced/#/customize-css */

.markdown-preview.markdown-preview {
  // modify your style here
  // eg: background-color: blue;
  h1,
  h2 {
    border-bottom: 1px solid #eaecef;
  }
}

.md-sidebar-toc.md-sidebar-toc {
  padding-top: 40px;
}

#sidebar-toc-btn {
  bottom: unset;
  top: 8px;
}

更新履歴

2018年07月21日　初版
2018年11月10日　Markdown All in Oneを追加、その他細かい変更
2019年06月22日　Prettier と markdownlint の競合についてを削除
　　　　　　　　 MPEのPDF出力について、phantomjsサポート終了に伴う内容修正
2020年05月26日　MPEのUNCパス（共有フォルダ）のファイルがプレビューできない問題が修正された件
2020年06月21日　少し追記。settings.jsonの修正