はじめに
Markdownで資料作成だ！ということでVSCodeでMarkdownを書くためにまずは環境を整えたいと思います。
Markdownで資料作成するにあたりやりたいことは以下の5つです。
- とりあえず書ける環境を作りたい
- 完成した資料をPDFで書き出したい
- 完成資料を完成時の見た目でプレビューしながら資料作成したい
- Mermaidで図なんかも書きたい
- 正しいMarkdown記法で書きたい
上記の項目別にやるべきこと(適当な拡張機能の追加)を分けて書いていこうと思うので、参考になりそうな部分お読みいただければと思います。
環境構築するPC等の環境
- Mac OS 13.0
- Visual Studio Code 1.84.2
VScodeは既にPCに入っているものとして以下環境構築行っていきたいと思います。
1. とりあえず書ける環境を作りたい
実を言うと最低限書くだけならばVSCodeの基本機能で十分かもしれません。
- 章立てして文章書く
- 図表を挿入する
- 書きながら文章をプレビューする
ようなことだけでOKであれば、VSCodeの基本機能で十分できてしまいます。
公式のドキュメントにできることは書いてあるので、一読してみると良いかと思います。
その上で入れておくととても便利なのがMarkdown All in One です
リンクのインストールボタンまたはVSCodeの拡張機能よりインストールできます。
- 文章に目次を入れたい
- オートコンプリート・ショートカットなど使ってスラスラ書きたい
- 箇条書きいい感じに整形して欲しい
など痒いところに手が届く機能がつまっています。
個人的にあって嬉しいのは、画像を挿入したいときにファイル名のオートコンプリートが働く瞬間です。
2. 完成した資料をPDFで書き出したい
PDF書き出しにはMarkdown PDFという拡張機能です。
こちらもリンクのインストールボタンまたはVSCodeの拡張機能よりインストールできます。
PDFだけでなく、HTMLやpng,jpegでの書き出しにも対応しています。
Mermaidなどで図のみ作成して画像として書き出しておいて別のところで使う、なんてこともできるのかなと思います。
書き出しは以下の2つの方法でできます。
- 右クリックして開くメニューから形式を選択して書き出し
-
F1またはcmd+shift+Pで開くコマンドパレットにmarkdown ~~と入力して出てくるコマンドを選択して書き出し
また今回ドキュメントをよく読んでみて初めて知ったのですが、Markdownを保存するたびにPDFヘ自動変換するという設定も行うことができるみたいです。
ドキュメントのUsege>Auto Convertの項目を参照ください。
3. 完成資料を完成時の見た目でプレビューしながら資料作成したい
こちら地味に困る時があるのですが、デフォルトのプレビュー機能では書き出される書面そのものをプレビューしてくれているわけではありません。例えば、VSCodeをダークモードで使用しているとプレビューで表示される書面の背景色もその時設定されている背景色と同様の黒となります。
完成資料そのものを眺めながら体裁整えたりしたいんだー！という場合にはMarkdown Preview Enhancedという拡張機能がおすすめです。
拡張機能追加後のプレビュー画面は以下
ヘッダの余白なんかも含めて、出力される通りにプレビューしてくれます。
この拡張機能、入れるとできるようになることが多いので私自身まだ全然使いこなせていません。
できることが増える一方で、前までの感じでVSCode動いてないな？と戸惑う瞬間もあったりするので一長一短あるかなとは思います。
入れてみて戸惑ったことは後日記事にできたらなと思います。 してみました↓↓
4. Mermaidで図なんかも書きたい
VSCodeでMermaid書きたい場合は拡張機能Markdown Preview Mermaid Supportをインストールします
設定からMermaidのテーマの変更なども簡単にできるので大変助かります。
5. 正しいMarkdown記法で書きたい
拡張機能markdownlintを入れます
正直正しい書き方わからなくてもなんとなくそれっぽく書けちゃうのがMarkdownだと思うのですが、他人と共有したりする場合はできるだけ良いとされている書き方で書いておいた方がいいのではないかと思っています。
おわりに
さしあたっての技術文書作成に導入した拡張機能一式でした。
他にもこんなの入れとくといいよ！みたいなおすすめあれば教えてください！