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](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)』をインストールします。

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

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

```json:settings.json
"editor.formatOnSave": true
```

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

[PrettierでMarkdownをフォーマットしたときの英語と日本語の間に入るスペースをどうにかする](https://qiita.com/kumapo0313/items/92d1597da5f3752f6584)

## 2. markdownlint をインストール

拡張機能『[markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)』をインストールします。

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

## 3. Markdown Checkbox

拡張機能『[Markdown Checkbox](https://github.com/PKief/vscode-markdown-checkbox)』をインストールします。

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

## 4. Markdown Preview Enhanced

拡張機能『[Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced)』をインストールする。

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

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

### PDF 出力できるようにする

<font color="Red">__※MPEバージョン0.4.0でphantomjsのサポートが終了となりました。__</font>

>* 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 にした状態で、下記のコードを貼り付けてプレビュー表示してみてください。

```txt
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`を開きます

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

    ```less:style.less
    // サイドバーTOCを左上にする
    .md-sidebar-toc.md-sidebar-toc {
      padding-top: 40px;
    }

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

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

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



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

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

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

```json: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`を開きます
1. 以下のようにします

    ```css
    .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](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)』をインストールします。

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

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

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

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

### Markdown All in One のユーザー設定

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

```json
"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）

```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を開く

```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の修正