この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
みなさん、Markdown書いてますか?
私が所属する事業開発部では、prismatixというサービスの開発をしています。そして、その仕様書などのドキュメントの多くがMarkdown形式で書かれています。そのため、私も日々Markdownを書いているのですが、その編集環境をできれば快適なものにしたいと思って試行錯誤しています。
本エントリでは、私が求める理想的なMarkdown編集環境に対し、現在どのような手段で実現しているか紹介します。
TL;DR;
- 現時点ではIntelliJ IDEAとそのプラグインが良い
- VSCodeとその拡張も捨てがたい
- Vimでもそれなりに行ける
Markdown編集環境に求めるもの
現在作成しているドキュメントには次のような特徴があります。
- プロジェクトリポジトリにソースとドキュメントが同梱されている
ソースとドキュメントは不可分なものであり、一緒にバージョン管理されるべきです - MarkdownにPlantUMLが埋め込まれている
設計文書に必要なクラス図、状態遷移図、シーケンス図は、UMLをテキスト形式で書けるPlantUMLで表現しています - 開発言語はJava
ドキュメントに直接関係するものではありませんが、編集環境を選ぶ際の視点の一つです
これらのことから、私がMarkdown編集環境に求めるものは、次のようなものです。
- 開発環境と共用
- Markdownのハイライト
- Markdownのプレビュー
- PlantUMLのハイライト
- PlantUMLのプレビュー
- Vimキーバインド(これだけは好み)
上記の要求に対して、色々編集環境を試行錯誤してきました。その中で良さそうな3つを紹介します。
IntelliJ IDEA + Markdown support Plugin + PlantUML integration Plugin + IdeaVim Plugin
現在のメインの編集環境です。コードと一緒に扱うのに都合が良いのが一番の理由です。
ただ、色々不都合があったので設定で回避しています。
要求へのマッチ状況
- ○ 開発環境と共用
- ○ Markdownのハイライト
- ○ Markdownのプレビュー
- × PlantUMLのハイライト
- △ PlantUMLのプレビュー
- ○ Vimキーバインド
メリット
- みんな大好きIntelliJ IDEAから出なくて良い
- IdeaVimのVim再現度がそこそこ良い(日本語もある程度)
- (公式には)IntelliJ IDEAはPlantUMLプレビューをサポートしている
Markdown - Help | IntelliJ IDEA
デメリット
- Markdownプレビューがダークテーマでテーブルがフル幅になってしまう
- Markdownプレビュー内でのPlantUMLプレビューが私の環境では動かない
- PlantUML integrationプラグインを使い、別窓でPlantUML部分のみプレビューすることで回避している
- IdeaVimは
q
,:
によるコマンド履歴をサポートしていないのでたまに面倒臭い
Markdownプレビューの見た目変更
Markdown supportプラグインはCSSで見た目をカスタマイズできるため、GitHubに近い好みの形にしています。
Before
After
CSS例
/*
背景色、文字色指定
*/
body {
background-color: white;
color: #24292e;
}
/*
テーブルの整形
- 既定だとページ幅いっぱいになっていたのをやめる
- ヘッダーを見やすくする
*/
table {
width: auto;
border-collapse: collapse;
border-spacing: 0;
border-width: 1px;
}
td, th {
min-width: 100px;
background-color: #f9f9f9;
border-color: #eeeeee;
}
th {
font-weight: bold;
}
/*
コード
*/
pre, code {
background-color: rgba(27,31,35,0.05);
font-size: 85%;
color: #24292e;
}
/*
引用
*/
blockquote {
color: #6a737d;
}
Visual Studio Code + Markdown Preview Enhanced拡張 + Vim拡張
次点の編集環境です。日本語の扱いがもう少しなんとかなって欲しいですが、開発環境と共用しないならかなり良いと思います。
要求へのマッチ状況
- △ 開発環境と共用
- ○ Markdownのハイライト
- ○ Markdownのプレビュー
- ○ PlantUMLのハイライト
- ○ PlantUMLのプレビュー
- △ Vimキーバインド
メリット
- みんな大好きVSCodeで豊富な拡張が使い放題
- コードブロック内のPlantUMLがハイライトされる
- Markdownプレビュー内でPlantUMLもプレビューできる
q
,:
も限定的に使える(履歴を元に変更して実行とかはできない)
デメリット
- vscode-vimはVSCodeの都合で日本語の単語の扱いが残念
いわゆる全半角関係なく空白までを一つの単語と見なしてしまうので、ciw
などが使いにくい - Javaのコードと一緒に扱うのはちょっと
VSCodeはJavaサポートしているけど、ちゃんとやろうと思うとIDEには敵わない
Vim + Markdown Preview Plus Chrome拡張
Vimをフルパワーで使えるので、簡易的なドキュメントならこれでやっちゃいます。
要求へのマッチ状況
- △ 開発環境と共用
- ○ Markdownのハイライト
- ○ Markdownのプレビュー
- × PlantUMLのハイライト
- × PlantUMLのプレビュー
- ◎ Vimキーバインド
メリット
- フルパワーのVimが使える
- ブラウザでプレビューできる
デメリット
- PlantUMLサポートがない
- Javaもつらい
その他補足事項
Markdownに埋め込まれたPlantUMLを見るには、弊社の都元ダイスケが作成したPegmatiteが便利です。
また、純粋にMarkdownを書くだけなら、弊社の阿部信介が紹介したTyporaのような専用ソフトを使うのも良いかもしれません。
それでは、みなさんもハッピーMarkdownライフを!