【ドキュメントが書きたくなる】Markdownライブプレビュー + インライン数式/UML/図表 + 綺麗にPDF/Wordエクスポートまで

# これはなに

インライン数式、UML、図表をライブプレビューしながらMarkdown+αで記述でき、PDF/Word/HTMLなどへのエクスポート機能をもつAtomプラグイン`markdown-preview-enhanced`を紹介します。
これを使うと、ドキュメント作成が捗ること間違いなし。

Github上では、Packageは2016年3月に開発スタートし、継続して成長しています。

(16.9.23追記) 図表を含めたexportは、pdf, html exportでは使えるが、`pandoc` では未対応([Issue #138](https://github.com/shd101wyy/markdown-preview-enhanced/issues/138), [pandoc export機能詳細](https://github.com/shd101wyy/markdown-preview-enhanced/blob/master/docs/advanced-export.md))。word形式を使いたい時に課題あり。取り込みに期待です。


![](https://i.github-camo.com/001a3a3c5344cbeed6b7074b12777d489583f808/68747470733a2f2f636c6f75642e67697468756275736572636f6e74656e742e636f6d2f6173736574732f313930383836332f32323736333037322f33326630396538302d656532382d313165362d396434322d6333393533663537343961312e676966)
> https://atom.io/packages/markdown-preview-enhanced より引用


# 準備

下記を導入する必要があります。

- テキストエディタ[Atom](https://atom.io/)
	- 同プラグインの[markdown-preview-enhanced](https://github.com/shd101wyy/markdown-preview-enhanced)
	- markdown-preview-enhancedが使うライブラリ
		- [Pandoc - About pandoc](http://pandoc.org/)
			- 詳細は[多様なフォーマットに対応！ドキュメント変換ツールPandocを知ろう - Qiita](http://qiita.com/sky_y/items/80bcd0f353ef5b8980ee)を参照
		- [Graphviz | Graphviz - Graph Visualization Software](http://www.graphviz.org/)
			- Graphvizは AT&T研究所が開発したオープンソースのツールパッケージ。dot言語のスクリプトで示されたグラフを描画できる。PlantUMLを使うために必要


## markdown-preview-enhancedの導入

- メニュー `Atom> Preferences`を起動
- `Install`を選択
- `markdown-preview-enhanced`を検索し、`Install`を押す


## 依存ライブラリの導入
### Macの場合

homebrewをお使いなら、下記で一発です

```
$ brew install pandoc graphviz
```

### その他環境

下記などを参照する

- [Pandocの比較的簡単なインストール方法 - Qiita](http://qiita.com/sky_y/items/3c5c46ebd319490907e8)
- [Graphviz をインストールする](http://ruby.kyoto-wu.ac.jp/info-com/Softwares/Graphviz/)


# 使ってみる
## ライブプレビュー

Markdown形式で記述したドキュメントの体裁をライブプレビューで確認できる。

- メニュー `Packages> markdown-preview-enhaned> Toggle` または、`ctrl + shift + m` で起動

> 注: ショートカット `ctrl + shift + m` がかぶるので、 `markdown-preview`をDisableしておく


## インライン数式/UML
### 数式を埋め込む

`KaTeX`や、`MathJax`が使うことができる。`$...$`や、`$$...$$`記法をサポートしている。

![](https://i.github-camo.com/6a2327a17ec260836bd7935f6128e69ae12e7859/68747470733a2f2f636c6f75642e67697468756275736572636f6e74656e742e636f6d2f6173736574732f313930383836332f31343339383231302f30653430383935342d666461382d313165352d396562342d3536326437633063613433312e676966)
> https://atom.io/packages/markdown-preview-enhanced より引用


### UMLを埋め込む

PlantUMLというDiagram as a Codeを実現できるUML記法がある。
> [PlantUML: Open-source tool that uses simple textual descriptions to draw UML diagrams.](http://plantuml.com/)

AtomではPlantUMLをライブプレビューしてくれる `plantuml-viewer` はとても良い。
> [AtomとPlantUMLで爆速UMLモデリング - Qiita](http://qiita.com/nakahashi/items/3d88655f055ca6a2617c)

具体的には下記のUMLを作成できる。

- シーケンス図
- ユースケース図
- クラス図
- アクティビティ図
- コンポーネント図
- 状態遷移図
- オブジェクト図

`markdown-preview-enhanced` では、下記の書式で、PlantUMLをドキュメントに埋め込んだ状態で編集できる。

```
```{puml}
A -> B
` ``
```

### 図表を埋め込む

他にも下記のような図表埋め込みに対応している。
- [mermaid](https://knsv.github.io/mermaid/) でガントチャート、フローチャートを描画する

![](https://i.github-camo.com/6b0f1b4b8cd95820d20269d028801daf6a30dc04/68747470733a2f2f636c6f75642e67697468756275736572636f6e74656e742e636f6d2f6173736574732f313930383836332f32333338333935362f35633863623337652d666430652d313165362d386132322d6633393436383431626262642e676966)
> https://atom.io/packages/markdown-preview-enhanced より引用


- [Viz.js](http://mdaines.github.io/viz.js/) でGraphviz互換、`.dot`形式で有向グラフ等を描画する
- [WaveDrom](http://wavedrom.com/) でデジタル信号のタイミングダイアグラムを描画する

に対応している。そのため、Atom内で完結して、文章と図表や数式を組み合わせたドキュメントが作成できてしまう。
ほんと感動した。


## エクスポート

どこかに提出したり、レビューしてもらう時に使う。pdf, wordなどにエクスポートを出し分けられる。
`front-matter` を下記書式で文頭に書いた上で、プレビュー画面のコンテキストメニューから`Pandoc`を選択する。

```
---
title: 	"{タイトル}"
author: {あなたのなまえ}
date: 	{日付}
output: word_document
---
```

（指定がないと、「エクスポート形式指定がない」と怒られる）
`title`, `author`, `date` は文頭に挿入される。`output`で指定した形式で出力される。

## スライドを作成する
(追記中)



## その他
### wordデフォルトテンプレートの水色の見出しが気持ち悪いよ！

のひとは下記などを参考に、テンプレートを差し替える。

[プログラマの文書作成術：Markdown, LaTeXなどの文書からWord文書を生成する - Qiita](http://qiita.com/sky_y/items/aab3f93a32a711a54e74)