こんにちは
今回はドキュメント作成のための記法のご紹介です。
ドキュメントは何で作る？
皆さんは手順書などのドキュメントを作成するとき、どんなツールを使いますか？
Word, Excel, PowerPoint などの Office ソフト？テキスト？HTML？
Office ソフトを使ってドキュメントを作ると、文字サイズ変えたり図形を追加したりと色々な操作が簡単にできます。
しかしこれには、Office 対応ソフトが入っていないパソコンやスマホでは見られないという欠点もあります。
どの環境でも見られるように、メモ帳アプリなどで書くことも出来ますが、これでは見出し文字を大きくしたり画像を追加することができません。
さまざまなデバイスで見られてかつ文字サイズ変更や画像の追加ができる記法と言えば、Web サイトを作成するときにも使用する HTML がありますが、少し専門的なスキルが必要で技術者でない方には取っつきづらいです。
そんな悩みを解消するために今回紹介するのは、 Markdown と呼ばれる記法です。
主な特徴に、
- 書き方が簡単で覚えやすい
- テキストファイルなので読み書きするだけなら特別なアプリが必要ない
- Markdown 表示に対応したアプリやサイトでは整形された状態で見られる
があります。
Markdown で何ができる？
では早速、具体的にどんなことができるのかを紹介します。
またそれぞれ、 Markdown での書き方も載せておきます。
見出し（大）
こんな風に見出しをつけたり
# こんな風に見出しをつけたり
↑ Markdown での書き方
見出し（中）
さっきよりちょっと小さい見出しをつけたり
## さっきよりちょっと小さい見出しをつけたり
↑ Markdown での書き方
引用
引用してみたり
> 引用してみたり
↑ Markdown での書き方
区切り線
区切り線を ↓
入れてみたり↑
区切り線を ↓
---
入れてみたり↑
↑ Markdown での書き方
箇条書き
- 箇条書き
- することも
- できます
- 箇条書き
- することも
- できます
↑Markdown での書き方
できることを見てみて、メモ帳に書くときのような書き方だな。と思われた方もいらっしゃるのでは？
ほんとにその通りだと思います。メモ帳に書くような書き方で書けるのに、対応したツールやサイトで見るときれいに整形されて見えるのが、 Markdown の大きな特徴です。
どうやって Markdown を書く？
そろそろ皆さん Markdown でドキュメントを書きたくなったと思いますので、いよいよMarkdown を書くために用意するものを紹介します。
- メモ帳などのテキストエディタ
これが Markdown を書くために最低限必要なツールです。シンプルですね。
ただもう少し簡単に読み書きしたいので、プログラマー御用達の無料コードエディタである VSCode を使って書いてみます。
- 拡張子を.mdでファイルを新規作成します。
- Markdown記法でファイルに内容を書きます。
これだけです。
ちなみに、 VSCode のファイル名タブを右クリックして「Open Preview」をクリックで、プレビューできます。
また Markdown All in One という拡張機能を追加すると、目次を自動でつけたり体裁を自動で整えてくれたりして、より便利に Markdown を書くことができます。
他にもこんなことができるよ
ここで紹介していないもので、Markdownを使うとこんなことができるよ！というものを紹介します。
テーブル
| 作品名 | 公開年 | ひとこと |
|---|---|---|
| 君の名は。 | 2016 | すごく良かった |
| 天気の子 | 2019 | まだ見てないからぜひ見たい |
| すずめの戸締まり | 2022 | めっちゃ良かった |
|作品名|公開年|ひとこと|
|-|-|-|
|君の名は。|2016|すごく良かった|
|天気の子|2019|まだ見てないからぜひ見たい|
|すずめの戸締まり|2022|めっちゃ良かった|
↑ Markdown での書き方
このように文字だけで簡単に、テーブルを書くことができます。また書く際のツールによっては、自動で縦位置を揃えてくれるのでテキストで見るときも見やすくなります。
↓ 例えば VSCode の Markdown All in One でフォーマットすると、このように整形してくれます。
| 作品名 | 公開年 | ひとこと |
| ---------------- | ------ | -------------------------- |
| 君の名は。 | 2016 | すごく良かった |
| 天気の子 | 2019 | まだ見てないからぜひ見たい |
| すずめの戸締まり | 2022 | めっちゃ良かった |
チャート
graph TD;
A[朝起きる] --> B{平日かどうか}
B --"平日"--> C[次のアラームまで二度寝する]
B --"休日"--> D[アラームを止めて二度寝する]
↑ Markdown での書き方
これはmermaidという、ダイアグラム作成用ライブラリを使うことで、このようなチャート型式で見ることができます。
フローチャートの他にも、クラス図やシーケンス図、ガントチャートやダイアグラムなども書けます。
チャート作成でも、書くのはテキストだけで図形の位置調整を気にする必要がないので、簡単に書くことができます。
Markdown のすゝめ
Markdown は、GitHub や Teams 、 WordPress などのメジャーなサイトで利用可能ですし、対応していない場合でもプレーンテキスト(純粋なテキストファイル)として読み書きが可能なので、非常に使い勝手のよい書き方です。
さらに内容を変更した際の差分がどこなのかを見つけるのも、PowerPoint や Excel では難しいですが、 Markdown ではテキストファイルなので簡単に見つけることができます。
他にも Markdown でスライドショーを作るツールや PDF や画像で出力するツールもあり、配付する際にも便利です。
ちなみに、察しの良いみなさんなら既にお気づきかと思いますが今回のこのブログ記事も、実はすべて Markdown で書いています。
みなさんもぜひ、ドキュメント作成の際には Markdown で書いてみてください！