Markdown記法を全く利用していない社内でMarkdown記法について布教するためのメモです。

Markdownとは何か？

テキストファイルで構造的な文章を記述するための記法。

Markdown記法で記述されたファイルを適切なビューアで読み込むと、HTMLに変換していい感じに綺麗に表示できる。

GitHubでいい感じにREADME.mdファイルが表示されるのはこれ。

利点

平文テキストの記法が統一できる
Word等の特定のアプリに依存せず、テキストエディタが自由に選択できる
- エディタによっては入力補助が使える
ソースコードを挿入できる
テキストファイルなのでGit等でバージョン管理できる
- GitHub等のリポジトリマネージャは標準でビューア機能があり、いい感じに表示してくれる

欠点

表示には何らかのツールが必要
WYSIWYGではないのでエンジニア以外には向かない
ページ区切りという概念はない
画像のバイナリファイル自体を埋め込みできない
表を書くのがちょっと辛い

ツール (エディタ、ビューア)

テキストファイルが編集できるなら何でもよい。メモ帳でもいい。

モダンなエディタなら拡張機能を導入することでシンタックスハイライトや入力支援機能が使える。プレビュー機能を備えているものも多い。

以下、利用しているものを記載。

Visual Studio Code

Markdown All in One によって入力支援、markdownlint による文法チェックが可能
別カラムでのリアルタイムプレビューもできる
シンタックスハイライト
アウトライン解析

秀丸

Markdown記法強調表示定義ファイルでシンタックスハイライト可能
リアルタイムプレビューには HmCustomLivePreviewMD

Chrome

Markdown Preview Plus を導入するとChromeへファイルをD&Dするだけでプレビューできる。表示の自動更新もできるのでChromeで開きながらメモ帳で編集も可能。

記法について

下記参考。

Markdown記法サンプル集 - Qiita

記法についてはサービスによって方言というものがあり、必ずしも同じ記法が使えるわけではないので注意。表組みやシンタックスハイライトはMarkdown ExtraやGitHub Flavored Markdown (GFM) といった方言の仕様ではあるが、大体の表示系で使える。

今までは標準的な仕様というものが存在していしなかったが、現在はCommonMarkという仕様で標準化が進められつつある。GitHubが採用しているGFMはこの仕様をさらに拡張したものになっている。

以下、よく使うものを抜粋します。

改行・段落

改行1つだけだと無視されます。空行を1つ置くと段落分けされる。

段落内で改行したい場合は、行末にスペースを2つ書く。

見出し

# 見出し1
## 見出し2
### 見出し3
#### 見出し4

箇条書きリスト

- リスト1
  - リスト1-1
    - リスト1-1-1
    - リスト1-1-2
  - リスト1-2
- リスト2
- リスト3

番号付きリスト

1. 番号付きリスト1
  1. 番号付きリスト1-1
  2. 番号付きリスト1-2
2. 番号付きリスト2
3. 番号付きリスト3

行頭の数字が何であるかは無視されるため、全部1.で始めてもいい感じに番号を振ってくれる。

1. 番号付きリスト1
1. 番号付きリスト2
1. 番号付きリスト3

文字装飾

*斜体* _斜体_
**太字** __太字__

リンク

[表示テキスト](https://www.google.com)

画像表示

 ![代替テキスト](gazou.png "タイトル")

コード挿入

行内に含める場合、 `echo 'hello, world'` のようにバッククウォート1つで囲む。

複数行に渡る場合は、行頭にスペースを4つ置く。

上下にバッククウォート3つと言語名を書くとシンタックスハイライトされる。ただし、これはGFMの仕様。

```c
int main(int argc, char** argv)
{
    printf("hello, world¥n");
    return 0;
}
```

表組み

Markdown Extraの仕様。GFMでも使用できる。

|header1|header2|header3|
|:--|--:|:--:|
|align left|align right|align center|
|a|b|c|

Markdownを始めよう