ドキュメントをMarkdown(.md)で書くことが最近増えてきましたが、どうしても記法を忘れちゃうことがあるので、そのためのチートシートとしてまとめました。
ただ、Markdownは使う環境（GitHubとかRedmine）によって若干書き方が異なるので、あくまで参考までにということで・・・。
それぞれの環境での詳しい記法については利用しているサービスで確認した方が良いと思います。
目次
見出し
# レベル１の見出し
## レベル２の見出し
### レベル３の見出し
#### レベル４の見出し
##### レベル５の見出し
###### レベル６の見出し
それぞれHTMLタグの<h1>〜<h6>に対応してます。
実際にはこんな感じで表示されます。
レベル１の見出し
レベル２の見出し
レベル３の見出し
レベル４の見出し
レベル５の見出し
レベル６の見出し
リスト
順序なしのリスト
* 順序なしのリスト
* 順序なしのサブアイテム
* 別のアイテム
HTMLタグの<ul><li>に対応してます。
実際の見え方はこちら。
- 順序なしのリスト
- 順序なしのサブアイテム
- 別のアイテム
順序付きのリスト
1. 順序付きのリスト
1. 順序付きのサブアイテム
1. 別のアイテム
HTMLタグの<ol><li>に対応してます。
実際の見え方はこちら。
- 順序なしのリスト
- 順序なしのサブアイテム
- 別のアイテム
順序付きのリストでは順序を自動でインクリメントしてくれるので、目次とかを一度作った後に、目次を差し込みたいといった場合でも順序を書き換えることなく対応することができます。
引用
> 引用する文章
２行目の引用文
HTMLタグの<blockquote>に対応してます。
実際の見え方はこちら。
引用する文章
２行目の引用文
引用文の最初にだけ>を設定すれば、改行された文章も引用文の一部として解釈されます。
リンク
[リンクのテキスト](https://codelab.website)
HTMLタグの<a>に対応してます。
実際の見え方はこちら。
水平線
---
HTMLタグの<hr>に対応してます。
実際の見え方はこちら。
段落打つほどではないけど区切りを入れたい時とかに利用します。
強調
*強調する文字*
**強い強調をする文字**
それぞれ、HTMLタグの<em>と<strong>に対応してます。
実際の見え方はこちら。
強調する文字
強調する文字
Markdown自体は文字の色を制御できない（HTMLタグを挿入すれば可能ですが）ので、Markdownのみで文章を書く場合は、強調表現はよく使うことになると思います。
コード
ブロックコード
```python
def sample(self):
return self
```
バッククォート(`)で囲まれた部分をHTMLタグでいい感じに整形してくれます。
実際の見え方はこちら。
def sample(self):
return self
サーバなどの環境構築やプログラムの実装手順を説明する際などに、実際のサンプルコードを記述できるのでかなり説明が楽になる。
インラインコード
文章の中にも`sample code`のようにコードを埋め込むことができます。
実際の見え方はこちら。
文章の中にもsample codeのようにコードを埋め込むことができます。
文章中のメソッド名やクラス名などをインラインコードとして表現することで文章がかなり見やすくなると思います。
テーブル
| 左寄せのデータ | 中央揃えのデータ | 右寄せのデータ |
|:------------|:-------------:|------------:|
| この | この | この |
| 列は | 列は | 列は |
| 左に | 中央に | 右に |
| 寄ります | 寄ります | 寄ります |
それぞれ、HTMLタグの<table>に対応してます。
実際の見え方はこちら。
| 左寄せのデータ | 中央揃えのデータ | 右寄せのデータ |
|---|---|---|
| この | この | この |
| 列は | 列は | 列は |
| 左に | 中央に | 右に |
| 寄ります | 寄ります | 寄ります |
Markdownのテーブルを使用するときの難点は日本語の場合、等幅フォントを使用してないとどうしても列の区切りが揃わないというところですね・・・。
今も悲しい状態になってます・・・。
実際に利用するときは等幅フォントを導入するなどして、見た目が綺麗に見えるようにした方が良いと思います。
このテーブルが使えれば設計書でよく作る、機能一覧とか画面一覧、DB一覧などの一覧系のドキュメントも作成できるようになります。
Markdownを利用することで、Excelの方眼紙を作ったり、Wordのテンプレートを作ったりといった、開発に直接関係ない作業をかなり削減できるのではないかと思います。
もし、どうしてもWordじゃないとダメという方がいれば「Pandoc」というツールを使用するという選択肢もありかと思います。
「Pandoc」はMarkdowからWordなどにドキュメントを変換可能なツールなので、一度、Markdownで記述したドキュメントをPandocでWordに変換して見て実用に耐えうるかどうか検討してみるのもありだと思います。
様々なフォーマットへの変換に対応してますので、詳細知りたい方は下記サイトを確認して見てください。
コメント