Zenn
📘

visual studio codeでmarkdownを書く

2023/08/18に公開
VS Code
Markdown
Marp
tech

markdownとは軽量マークアップ言語のひとつである。
QiitaやZennなど技術系記事投稿サービスで記事を投稿する際に使われていたり、GithubのREADMEを記述する際にも使われている。
開発者にとっては切っても切れない関係にあるといっても過言ではないものである。
markdownエディタ兼ビューワーは現在、様々なものがある(筆者が使っていた中ではTyporaとmarktext/marktextが使いやすかった)がその中でもvs codeはmd用の拡張機能が数多く提供されており、比較的にmdを記述しやすい環境を構築することができる。
本記事ではvs codeでマークダウンを記述する際に必要な設定や拡張機能についてまとめる。

記法について

そもそもmarkdownの記法がわからないという方はZennやQiitaのMarkdown記法の記事を参考にすること。
https://zenn.dev/zenn/articles/markdown-guide
https://qiita.com/Qiita/items/c686397e4a0f4f11683d

プレビュー方法について

vs codeでマークダウンをプレビューするには以下の方法がある。

  • mdファイルのタブを右クリック -> プレビューを開くをクリック
  • プレビューしたいmdファイルをフォーカスした状態で画面右上のプレビューアイコンをクリック
    ※そのままクリックした際は右側のペインに、Altを押下した状態でのクリックの場合は同じペインにプレビュー)

拡張機能のインストール

まずは拡張機能のインストール

https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
マークダウンを記述するうえで様々な補完をしてくれる拡張機能。
目次の自動作成機能が便利。追加される機能やショートカットについては以下に綺麗にまとめられているので参考にする。
https://zenn.dev/ctrlkeykoyubi/articles/vscode-markdown-all-in-one

https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced
標準のマークダウンビューワでは表示できない記法などを拡張する拡張機能。
コードブロックに行数表示を加えたり、数式の挿入が可能となる。
Markdown Preview Enhanced版のプレビューを表示したい場合は、プレビューしたいmdファイルをフォーカスした状態で画面右上の一番左のプレビューアイコンをクリックする(右隣のプレビューアイコンはvs code標準のプレビューアイコン)。
※他のマークダウンビューワで正しく表示できないことがあるので、md形式では配布せずpdfでexportして配布するドキュメントには使ってもよいかもしれない。

https://marketplace.visualstudio.com/items?itemName=yzane.markdown-pdf
markdownファイルをpdf形式で出力する拡張機能。
Export (PDF)コマンドでエクスポートすることができる。

https://marketplace.visualstudio.com/items?itemName=fcrespo82.markdown-table-formatter
mdのテーブルの成形を簡易的にする拡張機能。
全角文字が含まれていると上手く成形できないことがある。

https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles
vs code標準のmarkdownプレビューをgithubテーマでプレビューする拡張機能。

https://marketplace.visualstudio.com/items?itemName=RomanPeshkov.vscode-text-tables
mdファイルでの表作成を補助する拡張機能。

https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode
vs codeでmarpを使うことができる拡張機能。
marpについては以下の記事も参照
https://zenn.dev/kabec_dev/articles/9906c0b83d2ccb

Tips

改行について

Markdownは末尾に半角スペース2つか<br>を記述することでプレビュー時に改行判定が行われる。
よって改行コードによる改行ではプレビュー上では改行されない。
拡張機能ごとに以下の設定をすることによって改行コードで改行判定させることができる。

Markdown(vs code標準のプレビュー機能)

  1. ctrl + ,で設定を開く
  2. Markdown > Preview: Breaksの項目にチェックを付ける

これにより段落内の改行に対して自動的に<br>が作成され、プレビューでも改行が反映される。

Markdown-preview-enhanced

  1. ctrl + ,で設定を開く
  2. Markdown-preview-enhanced: Break on Single New Lineにチェックを付ける

Markdown-pdf

  1. ctrl + ,で設定を開く
  2. Markdown-pdf: Breaksの項目にチェックを付ける。

目次の作成

Markdown All in OneのCreate Table of Contentsコマンドで目次を作成することができる。
※tocでもコマンドの最上位に表示される、こちらのほうが早い。

新たに見出しを作成すると目次が自動更新されるので非常に便利。
目次に表示したくない見出しについては見出しの接尾に<-- omit in toc-->を記述することで目次リストでは非表示にすることができる。

テーブルの作成

Text TablesのCreate tableコマンドで簡単に指定行列のテーブルを作成することが出来る。
ただし、[列(横)]x[行(縦)]で表形式を指定するので注意(行列ではなく、列行で指定)。
ctrl+ q -> ctrl + q でテーブルモードのON/OFFが可能、テーブルモード時は以下が実行できる。

  • 見出し行を作成後、最終列でEnterで次行が自動作成
  • 次行の１列名で- -> Enterで境界行を作成
  • データ入力行でTabやEnterで幅を自動調整

https://aimek-developer.blogspot.com/2019/10/vs-code-02.html

改ページの宣言

以下を記述することで、Markdown PDFでpdfにエクスポートした際に指定の場所でページを区切ることができる。

<div style="page-break-after: always;"></div>

個人的にページ区切り前に区切り線を付けたいので以下のように記述することが多い。

---

<div style="page-break-after: always;"></div>

Markdown PDFでGithubテーマでエクスポートしたい

以下の手順で設定できる。

  1. sindresorhus/github-markdown-cssをダウンロード
  2. github-markdown.cssの編集
    1. すべての.markdown-を削除(空文字で置換すると楽)する
      1. vs codeで上記ファイルを開く
      2. ctrl + hで置換モード起動で.markdown-で検索
      3. ctrl + alt + enterで一括置換
    2. code blockの折返しを設定する。
      以下のコードの white-space: pre;を white-space: pre-wrap;に変更
    body pre>code {
padding: 0;
margin: 0;
word-break: normal;
white-space: pre;
background: transparent;
border: 0;
}
    1. CSSの編集が終わったら、vs codeの%APPDATA%\Code\User\settings.jsonに以下を追記する。
      "markdown-pdf.includeDefaultStyles": false, // デフォルトのCSSを無効にする
// github-markdown.cssを指定
"markdown-pdf.styles": [
    "~/.vscode/extensions/yzane.markdown-pdf-1.4.4/styles/github-markdown.css"
],

https://www.jackjasonb.com/2021/03/22/markdown-pdf-css/

Markdown PDFで横向きでエクスポートしたい

以下の手順で設定できる。
エクスポートコマンド実行時に指定はできないようなので都度切り替えが必要。

  1. ctrl + ,で設定を開く
  2. Markdown-pdf: Orientationで検索
  3. portraitをlandscapeに変更

Markdown PDFでエクスポートしたpdfが中国語フォントになる

vs codeのアップデートなどが原因でフォントが中国語になることがある。
以下を参考に修正するのもありだが、アンインストールするのが手っ取り早い。
拡張機能のアンインストール後はvs codeを全て終了してから再度起動。
再度、拡張機能をインストールすればOK。
https://mckuraw.hateblo.jp/entry/2018/04/26/223336
https://qiita.com/tfukumori/items/ea7c7d90e279b4857b10

mdのプレビューを大きく表示したい

以下の拡張機能を使えばブラウザでmdをプレビューすることができる。
ただし、plantumlなどは描画できないので注意。
plantumlはMarkdown Preview Enhancedでのmdプレビュー時のみプレビュー可能。
https://zenn.dev/kabec_dev/articles/cd34f2e2f32662

plantumlを含めてpdfにエクスポートしたい

Markdown PDFはplantumlなどはエクスポートの対象外なのでMarkdown Preview Enhancedの機能を使ってpdfにエクスポートする必要がある。以下の手順でエクスポート。

  1. Markdown Preview Enhancedでのプレビューペインで右クリック
  2. Chrome (Puppeteer)にマウスオーバー
  3. PDFをクリック

表を整形したい

vs codeの標準機能でshift + alt + fで表をフォーマットすることができる。
対象のドキュメントの中の全ての表が整形されるので注意。特定の表だけ整形などはできない。

reference

Discussion