VSCode でちょっとでもMarkdown する
VSCode でmarkdown するなら,拡張機能も有意義に使っていきたい.
本記事では,以下2つの拡張機能を用いてVSCode でmarkdown を始めるための設定セットアップを紹介したい.
- Markdown All in One | Yu Zhang ver.3.4.0 (2020/11 現在)
- Markdown Preview Enhanced | Yiyi Wang ver.0.5.13 (2020/11 現在)
デフォルトでもある程度不自由しないが,いくつか変更を加えておきたい.
また,本記事で紹介する設定を以下の折りたたみにまとめておく.
settings.json まとめ (折りたたみ)
Ctrl+Shift+P
からコマンドパレットを開き,Preferences: Open Settings (JSON) を選択するとsettings.json が開かれる.
// markdown settings
"[markdown]": {
"editor.wordWrap":"on",
"editor.wordSeparators": "./\\()\"'-:,.;<>~!@# ○$%^&*|+=[]{}`~?.。,、()「」[]{}《》てにをはがのともへでや",
"editor.quickSuggestions": {
"other": true,
"comments": false,
"strings": false
},
"editor.snippetSuggestions": "top",
"editor.scrollBeyondLastLine": false,
"editor.padding.bottom": 250,
},
// default viewer settigs
// "markdown.preview.breaks": true,
// "markdown.preview.scrollEditorWithPreview": false,
// "markdown.preview.scrollPreviewWithEditor": false,
// Markdown All in One
"markdown.extension.toc.updateOnSave": false,
"markdown.extension.math.enabled": false,
// "markdown.extension.toc.slugifyMode": "vscode",
// Markdown Preview Enhanced
"markdown-preview-enhanced.previewTheme": "github-light.css",// default
"markdown-preview-enhanced.breakOnSingleNewLine": true,
"markdown-preview-enhanced.scrollSync": false,
"markdown-preview-enhanced.mathRenderingOption": "MathJax",
行頭が//
はコメントアウトされている.
keybindings.json まとめ (折りたたみ)
Ctrl+Shift+P
からコマンドパレットを開き,Preferences: Open Keyboard Shortcut (JSON) を選択するとkeybindings.json が開かれる.
// [Markdown]: Markdown All in One
{
"key": "ctrl+q",
"command": "markdown.extension.editing.toggleCodeSpan",
"when": "editorLangId == markdown",
},
{
"key": "ctrl+alt+q",
"command": "markdown.extension.editing.toggleCodeBlock",
"when": "editorLangId == markdown",
},
{
"key": "ctrl+alt+l",
"command": "markdown.extension.editing.toggleList",
"when": "editorLangId == markdown",
},
{
"key": "ctrl+Alt+m",
"command": "markdown.extension.editing.toggleMathReverse",
"when": "editorLangId == markdown",
},
// [Markdown]: Markdown Preview Enhanced
{
"key": "ctrl+alt+v",
"command": "markdown-preview-enhanced.openPreviewToTheSide",
"when": "editorLangId == markdown",
},
{
"key": "ctrl+alt+s",
"command": "markdown-preview-enhanced.toggleScrollSync",
"when": "editorLangId == markdown",
},
// [Markdown]: Snippets Shortcut
{
"key":"ctrl+alt+e",
"command":"editor.action.insertSnippet",
"args":{
"snippet": "***${1:$TM_SELECTED_TEXT}***$0",
},
"when": "editorLangId == markdown",
},
これに関しては,下のキーボードショートカット一覧を参照してほしい.
文書作成サポート機能の項でさまざまな機能について書きすぎて非常に長い記事になりつつあります.
VSCode でmarkdown ドキュメントを作成する環境を初めて構築する方はちょっとした読み物としてお楽しみください.
○ markdown のグローバル設定
markdown のグローバルのエディタ設定1を紹介しておきたい.
- エディタでの改行
- 区切れ文字の日本語対応
- スニペットの表示位置
- スクロールの最下端を一番上にしない
- スクロールの最下端位置を下から250にする
"[markdown]": {
"editor.wordWrap":"on",
"editor.wordSeparators": "./\\()\"'-:,.;<>~!@# ○$%^&*|+=[]{}`~?.。,、()「」[]{}《》てにをはがのともへでや",
"editor.quickSuggestions": {
"other": true,
"comments": false,
"strings": false
},
"editor.snippetSuggestions": "top",
"editor.scrollBeyondLastLine": false,
"editor.padding.bottom": 250,
},
markdown のみに有効なように指定しておいた.
この他のエディタのグローバル設定について,以下の限定共有記事にて紹介しておきます.
○ Markdown All in One
VSCode でmarkdown をするならまず入れるとされている基本的な拡張.
キーボードショートカット等のエディタに関するさまざまな機能を提供してくれる.上で示したkeybindings.json の多くはMarkdown All in One から提供されているコマンドをキーボードショートカットとしている.
■ settings.json
- 目次作成の際の上書き保存に対して目次が自動更新されるのを避ける
- 数式のレンダリング(KaTeX) を無効にする (レンダリングはMarkdown Preview Enhanced で行う.また,ビューワをMPE で行うので,有効にしていても利用できない.)
"markdown.extension.toc.updateOnSave": false,
"markdown.extension.math.enabled": false,
○ Markdown Preview Enhanced
MPE: Markdown Preview Enhanced の代表的な拡張機能として以下が挙げられる.
- MathJax / KaTeX による数式 (デフォルトではKaTeX)
- mermaid によるチャート作成
- Beamerによるスライド作成……等々
以下の記事や参考にある公式から機能の詳細を見ることが出来る.本記事では機能について取り扱わないので,ぜひ見ておくと良いだろう.
Visual Studio Code + markdown preview enhanced は最高なノートだと思う - Qiita
VSCode デフォルトでもビューワを利用できるが,今回ではMPE のビューワを用いる.
MPE のビューワを使用することのうま味は,CSS が比較的容易に変更できる点やビューワに簡易的な目次を表示させることが出来る点である.また,mermaid などのダイアグラム2を描くことが出来る点である.(そもそもMPE のビューワを使わずにはプレビュー出来ない.)
逆に,他のいくつかの拡張機能はVSCode デフォルトのビューワを拡張するものがあり,MPE のビューワには対応しないものがある.これらには注意をしておきたい.
また,MPE のビューワがmarkdown としてかなりリッチなものになっているため,異なるビューワ(パーサ3)を利用する場合には注意が必要となる.(Qiita にそのままmermaid などのダイアグラムを挿入できない等.)
■ settings.json
以下の設定をしておく.
"markdown-preview-enhanced.breakOnSingleNewLine": true,
"markdown-preview-enhanced.scrollSync": false,
"markdown-preview-enhanced.mathRenderingOption": "MathJax",
■ 数式レンダリング
markdown での数式レンダリングでは,おおよそ2種類の方法がある.MathJax6 とKaTeX7 である.これらにはいくつかの特徴があり,どちらの方が良いかは使用者によって意見が分かれる.
今回はMathJax でレンダリングするように設定している.KaTeX に変更したい場合は,"~.mathRenderingOption": "KaTeX"
とすれば良い.
以下に,およその違いとそれぞれの拡張機能のサポートしている数式レンダリングを表にまとめておいた.
MathJax | KaTeX | |
---|---|---|
レンダリング方法 | SVG | HTML+CSS |
レンダリング速度 | 遅い | 早い |
サポート環境 | 多い | 少ない |
Markdown All in One | × | ○ |
Markdown Preview Enhanced | ○ | ○ |
ローカルに閲覧するだけのノート等を作成するだけであれば,MathJax の方がLaTeX に使用感が似ていて便利だろう.
アクセススピードを問うような場面にあるならば,KaTeX を利用すると良いろう.
なお,Markdown+Math | goessner はMPE ビューワで使用できないので注意が必要である.
■ CSS を変更する
デフォルトでのビューワは背景色が#ffffff
, 文字色が#000000
となっている.エディタが暗いのにビューワがまぶしい場合がある.
CSS を変更して目に優しいものに変更しよう.
コマンドパレットからMarkdown Preview Enhanced: Customize CSS とすることでstyle.less8 を開けることが出来る.このファイルは以下のディレクトリに格納されている.
%USER%\.mume\style.less
以下のように編集してみよう.
.markdown-preview.markdown-preview {
// modify your style here
// eg: background-color: blue;
background-color: #222;
color: #fff;
h1,
h2,
h3,
h4,
h5,
h6 {
color: #fff;
}
}
色は任意に変更すると良いだろう.
2020/12/1 追記 : そもそも,CSS そのものを変更してしまった方が綺麗だとも思われる.
settings.json からCSS 9を変更しよう.
"markdown-preview-enhanced.previewTheme": "github-dark.css",
確認したCSS 10は以下の16がありました.
- atom-dark, atom-light, atom-material,
- github-dark, github-dark,
- gothic, medium, monokai, newsprint, night, none, vue,
- one-dark, one-light,
- solarized-dark, solarized-light,
○ キーボードショートカット一覧
keybindings.json で定義したショートカットも含めたキーボードショートカットを一覧にしておきたい.
キーボードショートカット | 効果 |
---|---|
Ctrl+I |
* で囲う (イタリック体) ※ |
Ctrl+B |
** で囲う (ボールド体) ※ |
Alt+S |
~~ で囲う (取り消し線) ※ |
Alt+C |
チェックボックスにx を入れる (チェックを入れる) ※ |
Ctrl+Q |
1つのバッククォートで囲う (インラインコード)11 |
Ctrl+Alt+Q |
3つのバッククォートで囲う (コードブロック) |
Ctrl+M |
$ で囲う (行内数式) ※ |
Ctrl+Alt+M |
$$ で囲う (行別数式) |
Ctrl+Alt+L |
選択した各行をリスト化する (繰り返し押下することで+ や1. に切り替え可能) |
Ctrl+Alt+V |
ビューワを右側に表示 |
Ctrl+Alt+S |
ビューワとのスクロール同期のオン / オフ |
Ctrl+Shift+S |
カーソル位置にビューワを移動 ※ |
ビューワ上で右クリックSync Soursce
|
ビューワの位置にエディタが移動 |
デフォルトのキーボードショートカットには※ を付与している.
好きなように作り変えても良いだろう.
2020/12/25 追記 :Ctrl+Alt+M
で定義しているコマンドについて,誤解をしていたので訂正しておきたい.
Ctrl+M
で提供されているコマンドは,繰り返して使用することで$
, $$
を切り替えることが出来るトグルであり,Ctrl+Alt+M
で定義したコマンドはそのトグルを逆回りするコマンドとなっている.
したがって,ほとんど同じコマンドを異なる2つのキーボードショートカットで定義していることになる.(1回の押下で済むという点のみでは意味がある.)
これに伴って,少しだけ以下のように変更しても良いだろう.
行別数式のためのキーボードショートカット (折りたたみ)
$$
で囲う際に1行で出して欲しくない.しかし,下のように出すにはCtrl+M
を2回押下する必要があったので,1回の押下で出るようにするために作り直した.
$$
$$
keybindings.json でCtrl+Alt+M
を以下のように変更した.
{
"key": "ctrl+Alt+m",
"command":"editor.action.insertSnippet",
"args":{
"snippet": "\\$\\$\n$1\n\\$\\$$0",
},
"when": "editorLangId == markdown",
},
○ 文書作成サポート機能
上のキーボードショートカット以外にも文書作成サポート機能がいくつかあるので紹介しておきたい.
■ スニペット
VSCode のデフォルトにあるmarkdown スニペット12を見ておきたい.
デフォルト スニペット (折りたたみ)
全部で18ある.
snippet | 効果 | |
---|---|---|
ボールド | bold |
** で囲う |
イタリック | italic |
* で囲う |
引用 | quote | > |
行内コード | code | 1つのバッククォートで囲う |
コードブロック | fenced codeblock | 3つのバッククォートで囲う |
見出し1 | heading1 | # |
見出し2 | heading2 | ## |
見出し3 | heading3 | ### |
見出し4 | heading4 | #### |
見出し5 | heading5 | ##### |
見出し6 | heading6 | ###### |
箇条書き | unordered list |
- , - , -
|
番号付き | ordered list |
1. , 2. , 3.
|
定義 | definition list |
<TERM> , :<DEFINITION>
|
水平線 | horizontal rule | ---------- |
リンク | link | [TEXT](LINK) |
画像 | image | ![ALT](LINK) |
取り消し線 | strikethrough |
~~ で囲う |
たいていの場合にはMarkdown All in One から提供されるコマンドとキーボードショートカットの方が利用しやすいだろう.
これらに加えて,改行のためのスニペットを定義しておきたい.
改行の対応をパーサ側で行うことも出来るが,パーサ側で改行を許さない場合にはこちらから強制的に改行させるしかない.
markdown では半角スペース2つを文末に置くことで改行させることが出来るが,見た目で判別しづらい.そのため,HTML から提供される<br>
タグを"break" から呼び出せるようにしておく.
また,脚注の作成のためのスニペットも用意しておく.
自作スニペット (折りたたみ)
Ctrl+Shift+P
からコマンドパレットを開き,Preferences: Configure User Snippets を選択し,markdown.json を開く.
"Insert break tag": {
"prefix": "break",
"body": [
"<br>",
],
"description": "line break",
},
"Insert footnote": {
"prefix": "footnote",
"body": [
"[^$1]",
"",
"[^$1]: $0",
],
"description": "footnote",
},
頻繁に利用する場合には,keybindings.json で以下のようにAlt+B
で<br>
タグを生成するように作成しても良いだろう.
{
"key":"alt+b",
"command":"editor.action.insertSnippet",
"args":{
"snippet": "<br>",
},
"when": "editorLangId == markdown",
},
■ URL を貼り付ける
URL はmarkdown では以下のように記述する.
[URL タイトル](https://~~)
Markdown All in One では,URL タイトルを選択した上からコピーしたURL をCtrl+V
することで簡単に作成することが出来る.
■ 表を作成する
Markdown All in One では,大雑把に表を作成しておいてShift+Alt+F
を押下するとドキュメント内の表すべてが綺麗に成形される.13
あるいは以下ような表作成支援ツールを用いると良い.Excel のように編集することが出来る.
また,MPE ではセルの結合を可能とする拡張を有効にすることが出来る.(デフォルトでは無効)
"markdown-preview-enhanced.enableExtendedTableSyntax": true
■ 目次を作成する
目次(TOC) は上で示した2つの拡張機能の両方で簡単に作成することが出来る.
もちろん,目次作成専用の拡張機能14もあるが,そこまでこだわらなくても問題ないように思う.
以下で示す方法はコマンドパレットからコマンドを実行する方法を取るが,上のようにキーバインドを作成しておいても良いだろう.15
▽ Markdown All in One の場合
コマンド | |
---|---|
markdown.extension.toc.create |
目次の作成 |
上書き保存16またはmarkdown.extension.toc.update
|
目次の更新 |
目次にする見出しの深さは"markdown.extension.toc.levels"
を変更する.ただし,これはグローバルに効いてしまう.
目次に含めない場合は,<!-- omit in toc -->
を目次に含めない見出しの最後に挿入する.
章番号に関しては,以下の2つのコマンドが提供されている.
コマンド | 章番号の操作 |
---|---|
markdown.extension.toc.addSecNumbers |
付与 |
markdown.extension.toc.removeSecNumbers |
取り除く |
<!-- omit in toc -->
が与えられている見出しには章番号はつかない.
▽ Markdown Preview Enhanced の場合
コマンドmarkdown-preview-enhanced.createTOC
を実行すると以下のような文が挿入される.
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
depthFrom
からdepthTo
までの見出しレベルまでが目次として作成される.
また,orderedList=true
とすれば目次に章番号が付与される.(ただし,各見出しには章番号は付与されないので注意)
上書き保存すると目次が作成される.
目次に含めない場合は,{ignore=true}
を目次に含めない見出しの最後に挿入する.(ただし,パーサによっては{ignore=true}
が見えてしまう場合がある)
▽ 個人的な目次への方策
両方が一長一短という感がある.表にしてみた.
Markdown All in One | Markdown Preview Enhanced | |
---|---|---|
章番号の付与 | 見出しと目次に付与 | 目次のみに付与 |
見出しレベル | グローバルに指定 | ドキュメント毎に設定可能 |
見出しのレベルはドキュメント毎に設定できた方が勝手が良いだろう.また,章番号は見出しと目次の双方に出してほしい.17
(見出しレベルをドキュメント毎に設定しない場合には,Markdown All in One のみで十分になるだろう.)
したがって,以下のような手順で目次を作成すると良いように思われる.
-
"markdown.extension.toc.updateOnSave": false
としておく - 目次に含まない見出しに
{ignore=true}
を挿入する - 章番号を付与しない見出しに
<!-- omit in toc -->
を挿入する -
markdown.extension.toc.addSecNumbers
を実行して章番号を付与する -
markdown-preview-enhanced.createTOC
を実行して見出しレベルを選択し目次を作成する -
<!-- @import "[TOC]" ~~ -->
と{ignore=true}
を削除する
目次を作成してから修正するのは少々面倒な方法ではある.
■ 引用符を作成する
Markdown All in One では引用符である>
をリストの作成のようなトグルコマンドを提供していない.
しかし,GitHub のPull requests を見ていると,以下のようなリクエストが挙がっていた.
そのうちにマージされて使えるようになるだろう.
■ チェックボックスを作成する
チェックボックス- []
をリストのように作成するために,以下の拡張機能を導入しても良いだろう.18
リストの作成と同様のコマンドを提供してくれる.また,チェックが入った後の動作にもバリエーションがありおもしろい.
チェックボックスのみの拡張機能なので,それほど難しいものではないようだ.
■ 脚注を作成する
Markdown All in One では脚注の作成を提供していない.19
スニペットの項で紹介しているようにスニペットを作成しても良いが,新たに拡張機能を導入しても良いだろう.
Markdown All in One では次の拡張機能を紹介している.
しかし,この拡張機能はVSCode デフォルトのビューワに脚注の機能を実装するのみだ.あまりうま味がある拡張機能ではない.また,MPE のビューワには脚注の機能は実装されているので必要がない.(VSCode のデフォルトビューワを使用する場合には価値があると言える.)
脚注を簡単に作成するコマンドを提供するような拡張機能があった.20
この拡張機能では,Markdown Footnotes("s" が付いている方) と同様にVSCode デフォルトのビューワに脚注の機能を実装している.
加えて,脚注の挿入のコマンドを提供しており,[^hoge]
と[^hoge]:
を挿入する.また,hoge
は任意に指定することが出来る.
使用した所感を書いておきたい.(Markdown Footnote ver. 0.0.5)
- "
[^hoge]
" にマウスを合わせると脚注内容をホバーで見ることが出来る.- "
[^hoge]:
" はドキュメントの末行に生成される.文書の途中に挿入したい場合にはかなり野暮ったい.- エディタ側で
Ctrl+click
すると相互にジャンプすることが出来るが,そのたびに警告のウィンドウが生成される.(生成の際には警告されない)[^hoge]
と[^hoge]:
の"hoge" を同時に変更することが出来ない.(あまりそのようなことをしないが)拡張機能を導入するも良し,スニペットを自作するも良し.どちらにせよまだ少し面倒さは残るようだ.
■ 他形式でエクスポート
やっべ,Markdown PDF 使うとデフォルトのビューワの出力になるので,良ろしくないや.
これらに関しては,他の拡張機能を導入した方が懸命なように思われる.21
公式ドキュメントとして日本語版もあったので,これを参考にすると良いだろう.
markdown からほかの形式に変換する場合,多くの場合HTML かPDF になるだろう.
MPE ビューワを右クリックすると,Open in Browser
やHTML
が表示される.
PDF の場合はブラウザからPDF として出力する方法がもっとも容易な方法になる.
PDF(prince) は現在使用できなくなっているので,もはやデコイとなっている.
- HTML
HTML の場合は,HTML
からoffline
かcdn hosted
を選択する.
自分以外が見るのであればcdn hosted
を選択する.
CDN については少々説明が面倒なので割愛.
■ その他
MPE の紹介は他の記事に譲ろうとしていたが,少し調べていておもしろかったのでいくつか紹介しておきたい.
ただし,これらの機能はMPE のビューワ内でふつうに使用できるものだが,他のパーサを利用する場合には少しのマジックが必要なことには注意が必要となる.(もちろん,すでに紹介しているいくつかの機能にもGFM やCommonMark などで採用されていないものもある.)
互換性を保持したい場合にはあまり使用しない方が良い可能性がある.
Markdown Guide では基本構文と拡張構文を紹介している.これを参照するのも良いだろう.
しかしながら,GFM やCommonMark などの枠組みにとらわれずに多くの機能が提供されているので,利用しない手も無いと言えるだろう.
- 絵文字
:smile:
などとすれば を表示させることが出来る.(Qiita でもできる)
- 上付き,下付き文字
^
, ~
で囲うことで上付き,下付き文字にすることが出来る.
30^th^
H~2~O
- あみかけ
==
で囲うことで網掛けを掛けることが出来る.
==あみかけ==
- Critic Markup
Critic Markup が使用できます.(デフォルトでは無効)
以下を参照してほしい.
CriticMarkup-toolkit: Various tools to use CriticMarkup in your daily workflow | GitHub
最後のContribution が2014年となっているので,利用して良いものか判断できなかった.(開発が止まっている?)
参考
追記
- 2020/11/26 : 「エディタのグローバル設定」の限定共有記事URL を追加しました.その他軽微修正.
- 2020/12/1 : MPE のCSS を変更する方法について追記.「数式のレンダリング」,「引用符を作成する」,「チェックボックスを作成する」を追加.その他軽微修正.
- 2020/12/25 : キーボードショートカットについて追記.「他形式でエクスポート」を改変.「スニペット」,「脚注を作成する」,「その他」を追加.ビューワについていくつか言及.
-
デフォルトでのエディタの設定は「Visual Studio Code User and Workspace Settings #_default-settings」 から. ↩
-
パーサ(parser) とは,構文解析を行う処理系のこと.ここでは,markdown からHTML に変換するプログラムを指すつもりで言っている.(CSS とは別.) ↩
-
デフォルトのビューワを使用する場合には
"markdown.preview.breaks": true,
としておけば良い. ↩ -
デフォルトのビューワを使用する場合には
"markdown.preview.scrollEditorWithPreview": false,"markdown.preview.scrollPreviewWithEditor": false,
としておけば良い. ↩ -
KaTeX | The fastest math typesetting library for the web を参照. ↩
-
CSS と言いつつ,編集するのは.less ファイルになる."Less" は"Leaner CSS" の略であり,CSS をより使いやすくメンテナンスしやすいCSS プリプロセッサのことだそうだ.CSS と同じように編集することが出来る. ↩
-
デフォルトのCSS はgithub-light.css になっている. ↩
-
ここに格納されていました.
%USER%\.vscode\extensions\shd101wyy.markdown-preview-enhanced-0.5.13\node_modules\@shd101wyy\mume\styles\preview_theme
↩ -
バッククォートで囲うショートカットは
Q
(back Quote) を使用するようにしている.本当は"Code" のC
を使いたかった.しかし,すでにデフォルトで使われていたので上書きにせずに避けた.引用(Quote) のコマンドが無かったので,これでも良いかなと思う. ↩ -
vscode/markdown.code-snippets at master | microsoft/vscode | GitHub より. ↩
-
経験則上,整列の
:--:
等があれば外側の|
が無くても作成される. ↩ -
そもそもTOC を作成する機会がそれほどないということもある.個人的には,目次をほとんど作成しないのでコマンドパレットでの実行で十分に感じている. ↩
-
デフォルトでは
"markdown.extension.toc.updateOnSave": true
となっているため.今回はfalse
として自動更新しないようにしている. ↩ -
Markdown All in One では見出しに章番号が付与されている.目次にはこれに連動して章番号が加えられている. ↩
-
実は,Issue にもチェックボックスのためのトグルコマンドが提案されていたので,そのうち使えるようになるかもしれない.Could checkTaskList add a checkbox if one isn't present? #842 | Markdown All in One ↩
-
Issue #212 | Markdown All in One で明らかなように,CommonMark とGFM のみをサポートする形でさまざまな機能を実装しているようだ.したがって,今後これらのmarkdown のいずれかに脚注機能が実装されない限りには,Markdown All in One には便利なコマンドなどは実装されないと思われる. ↩
-
リリース日が2020/8/15 とまだまだ日が浅い.また,使用感としても使い勝手が良いとは言い難いところが多々ある.開発が活発になればより良い拡張機能になるだろう. ↩
-
MPE でも他形式でエクスポートすることは可能だが,勝手が悪いように感じる.と言いつつも,あまりエクスポートすることもないので良く知らないのだが.また,MPE を利用してHTML やPDF に変換する場合,上で示したCSS の変更が影響する.編集中での見た目と最終的なエクスポートとしての見た目を同じにしないように場合にも有効的に利用することが出来るだろう.↩