ドキュメントを変える！Markdownの様々な活用法とおすすめツール ｜ SiTest (サイテスト) ブログ

こんにちは、プロダクト開発チーム エンジニアの森永です。

昔はドキュメントなどの記載といえば

• 素のテキストファイルを書く
• Wordなどのソフトを使う
• HTMLを書く

といった方法で書いていた人が多いかと思いますが、最近エンジニアの間で浸透してきている形式が「Markdown」です。

Markdownについては本ブログでも「ブログを3倍速で書ける！Markdownの活用方法」で取り上げておりますが、今回はMarkdown形式をドキュメント作成に活用する様々な方法、そして、Markdown形式のドキュメントを作成するために便利なツールを紹介いたします。

まず、改めてMarkdownについて説明いたします。

Markdownは基本的にプレーンテキストで記述されている文書なのですが、見出し、強調、リスト(箇条書き)などについて文法が存在し、簡単にHTML文書に変換することができるマークアップ言語です。2004年にジョン・グルーバーによって開発されました。

主な文法ルールは以下の通りです。

• 段落は空行で、一行開ける
• 見出しは行頭に「#」。「#」の数で見出しのレベルを調節可能
  (1つでHTMLで言うh1タグ相当、2つでh2タグ相当、以下「#」を増やしていくことにより同等のタグ相当)
• 強調したい部分を 「**」 で囲む
• 箇条書きは行頭に 「-」 (または「+」「*」も可)
• リンクは [ ] でリンクしたい文字を囲って、その直後の ( ) の中にURLを書く

例

### Markdownについて

**Markdown**は基本的にプレーンテキストで記述されている文書なのですが、

- 見出し
- 強調
- リスト(箇条書き)

などについて文法が存在し、簡単にHTML文書に変換することができるマークアップ言語です。[2004年にジョン・グルーバーによって開発されました]。(http://daringfireball.net/projects/markdown/)。

変換後の表示例

1. ドキュメントの記載

エンジニアにとってはソフトウェア、プログラムのドキュメントでMarkdownを最もよく見かけていると思われます。
実際、GitHubやQiitaなどでは、ユーザーがMarkdownで記載したドキュメントをサイト内で変換してHTMLとして表示しております。

2. ブログ

次に多いのがやはりブログ。詳しくは「ブログを3倍速で書ける！Markdownの活用方法」をご参照下さい。
また、はてなブログやTumblrなど、Markdownを標準の記載形式として採用しているところも増えてきています。

3. 議事録、メモなど

議事録、個人的なメモや記録などをMarkdownで記載して活用するのも良い活用法といえます。私自身もよくMarkdownで議事録やメモを作成していますが、後から見返しやすくかなり便利に感じております。

Markdownのドキュメントを作成するためのツールも様々なものが用意されています。先の活用法のうち、ブログ記事作成時はブログの作成画面から入力すれば良いケースが大半なので不要かもしれませんが、ドキュメント作成や議事録、メモなどでMarkdownを使う時に便利なツールを3つご紹介いたします。

MacDown

http://macdown.uranusjr.com/

Mac専用のMarkdown作成に特化したエディタ。議事録作成やメモ書きに使用しております。
左ペインでMarkdownドキュメントを編集すると右ペインでリアルタイムで変換されたものをプレビューすることができ、非常に便利です。

Sublime Text

https://www.sublimetext.com/

以前「エンジニアに人気！コーディングがスムーズに進むエディタ3選」で紹介したSublime Text。こちらについてもMarkdown形式の文書をサポートするプラグイン、並びに、Markdown形式の文書をHTMLに変換してプレビューを行うプラグインをダウンロードすることが可能となっております。

Boostnote

https://b00st.io/

こちらはエディタというより一時的なメモ書きを記録しておくためのツールです。一時的なメモ書きに特化しており外部ファイルに保存する機能はありませんが、こちらも標準でMarkdownをサポートしており、Markdownで作成したメモを変換して整形されたものを表示することが可能です。

これまでプレーンテキストやWordでドキュメントを作成していた方も、Markdownは覚えることがあまり多くないので取り掛かりやすいです。実際私もすぐに慣れてMarkdownでのドキュメント作成が増えました。
是非Markdownでより良いドキュメントを作成していきましょう！