ドキュメントを 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` タグでいい感じに整形してくれます。
実際の見え方はこちら。
```python
def sample(self):
return selfサーバなどの環境構築やプログラムの実装手順を説明する際などに、実際のサンプルコードを記述できるのでかなり説明が楽になる。
インラインコード
文章の中にも sample code
実際の見え方はこちら。
文章の中にもsample codeのようにコードを埋め込むことができます。
文章中のメソッド名やクラス名などをインラインコードとして表現することで文章がかなり見やすくなると思います。
テーブル
| 左寄せのデータ | 中央揃えのデータ | 右寄せのデータ |
|:------------|:-------------:|------------:|
| この | この | この |
| 列は | 列は | 列は |
| 左に | 中央に | 右に |
| 寄ります | 寄ります | 寄ります |それぞれ、HTMLタグの<table>に対応してます。
実際の見え方はこちら。
| 左寄せのデータ | 中央揃えのデータ | 右寄せのデータ |
|---|---|---|
| この | この | この |
| 列は | 列は | 列は |
| 左に | 中央に | 右に |
| 寄ります | 寄ります | 寄ります |
Markdown のテーブルを使用するときの難点は日本語の場合、等幅フォントを使用してないとどうしても列の区切りが揃わないというところですね・・・。
今も悲しい状態になってます・・・。
実際に利用するときは等幅フォントを導入するなどして、見た目が綺麗に見えるようにした方が良いと思います。
このテーブルが使えれば設計書でよく作る、機能一覧とか画面一覧、DB一覧などの一覧系のドキュメントも作成できるようになります。
最後に
Markdown を利用することで、 Excel の方眼紙を作ったり、 Word のテンプレートを作ったりといった、開発に直接関係ない作業をかなり削減できると思います。
もし、どうしても Word で設計書などを作成しないといけないという方がいれば「Pandoc」というツールを使用するという選択肢もありかと思います。
「Pandoc」は Markdow から Word などにドキュメントを変換可能なツールなので、一度、 Markdown で記述したドキュメントをPandocで Word に変換して見て実用に耐えうるかどうか検討してみるのもありだと思います。
様々なフォーマットへの変換に対応してますので、詳細知りたい方は下記サイトを確認して見てください。
コメント