## はじめに
横浜工文社のエンジニアやライターがたいへんお世話になっているMarkdownについての解説です。
過去に作成した社内メモを修正して公開します。
> このページのMarkdownソース → [View](about_markdown_md.html) or [Download](about_markdown.md)
MarkdownはWikiTextのひとつなのでまずはそこから...
## WikiTextとは
WikiTextはWebですばやく情報を共有する手段として生まれた。
「Wiki」はハワイ語で「速い」という意味。
Webブラウザで接続したWikiサイトで簡単な書式ルールにしたがってテキストを書くと、それがHTMLに自動変換されてみんなで閲覧できるようになる。
テキストで書いた原稿から閲覧用のファイル、たとえばHTMLやPDFを生成できるため、Web以外でも使われている。軽量マークアップ言語（lightweight markup language）とも呼ばれる。
WikiTextにはたくさんの種類があるがめぼしいものをあげると:
| Name | Description |
|---|---|
| Markdown | GitHubで公開したソフトウェアの説明書（README）を書くのに使われている |
| MediaWiki | WikiPediaで記事を書くのに使われている |
| WikiWikiWeb | 最初のWikiTextと呼ばれるもの。ホノルル空港のシャトルから命名された |
| KTF | 工文社のマークアップ言語。RTF/HTML/FrameMaker形式などの文書から書式情報を損なわずにテキストを抽出。翻訳や編集を行ったあと元の形式に復元する。 |
種類が異なるWikiTextで何が違うのかといえば、書式ルールが違うにすぎない。
## WikiTextの表現
ふつうのテキストを書きつつ、次の効果が実現できる。
- 文字の修飾
- 見出し、箇条書き、コード、引用、注記、表などの段落の表現
- 他文書へのリンクや画像、ビデオが組み込める
- HTMLのタグを直接テキストに埋め込む
## WikiTextの使われ方
WikiTextはさまざまなかたちで利用されている。
### ★Wikiサイト
WikiTextが使えるサイトのページで、テキストの作成、編集、プレビューが行える。保存して終了すればHTMLのページとして表示される。
ブログサイトやフォーラムなど様々なところで活用されている。
本来のWikiTextの使い方。
オープンソースソフトウェア公開サイトのGitHubでは、Markdownで書いたテキストファイルに拡張子mdを付けて登録すると、それをHTMLで表示してくれる。
例: [github.com/kobucom/author](https://github.com/kobucom/author)
そのほか、バグ管理サイトのBacklogやRedmineではチケットのコメントをMarkdownで書ける。
またWebのChatアプリではたいてい簡単な書式が使えるものがある（引用や強調など）。
### ★開発環境で
プログラム開発用エディタや、デバッグもできる統合開発環境（IDE）を使いつつそのなかで、ドキュメントをWikiTextで作成、プレビュー、HTMLなど閲覧形式への変換ができる。
Eclipse IDEではMarkdownやTextileなど数種のWikiTextが使え、プレビュー、HTML/PDF/DocBook/RTFへ変換が行える。
Visual Stduio Codeでは、そのままでMarkdownのテキスト作成、プレビューができる。エクステンションを組み込めば、HTMLやPDFに変換できる。この文書はそうして作っている。
### ★変換ツール
パソコン上で変換プログラムを使えば、WikiTextを各種閲覧形式に変換できる。
Markdownでは、markdown-itというnode.js (Javascript)の変換ツールが有名。
工文社ではWebサイトでMarkdownソースをHTMLに自動変換するのにPandocという変換ソフトを使っている。
KTFも主にこの方法で使っていたが、現在はWebサービス（USF）として使っている。
>KTF/USFは2015廃止。Markdownに切り替えたため。
## スタイルシート
Markdownから変換されたHTMLファイルに適用されるスタイルシート（CSS）の取り扱いはサイトや変換ツールによって様々。
Wikiサイトの場合はもとはサイトのデフォルトのスタイルシートが適用されているが、自前のものに変更できる場合もある。
変換ツールの場合は固定のスタイルシートから変更できない場合もあるが、たいていは引数で指定できるようになっている。
## Markdownの書き方
このページの残りで、Markdownの書式ルールを紹介する。
同じMarkdownといっても様々なバージョンがあり使える書式に違いがある。
たとえば、Markdownではもともと表が書けなかったが、現在はたいていのサイトや変換ツールで表が使えるようになっている。
どの書式を使えばよいかというと、GitHubで使われている書式が有力だと思う。
GitHub-Flavored Markdown (GFM)と呼ばれる。
以下、これを使ってよく使う書式の説明をする。
### ★テキスト
テキストはふつうにタイプする。
改行一個では段落は変わらない。
改行二個で段落を分ける。
```
行1
行2
行3
行4
```
行1
行2
行3
行4
空行を挟まずに改行したい場合は前の文の最後に空白をふたつ追加する。
```
続きの文だが、ここで
区切りたい。
```
続きの文だが、ここで
区切りたい。
### ★見出し
行頭にシャープを付ける。
```
# 見出し1
地の文
## 見出し2
地の文
### 見出し3
...
```
# 見出し1
地の文
## 見出し2
地の文
### 見出し3
地の文
### ★箇条書き
行頭にハイフンかアスタリスク（*）を付ける。
二段目は空白ふたつ分下げる。
```
- 箇条書き1
- 箇条書き2
- 箇条書き2-1
- 箇条書き2-2
- 箇条書き3
```
- 箇条書き1
- 箇条書き2
- 箇条書き2-1
- 箇条書き2-2
- 箇条書き3
### ★文字の修飾
アスタリスクか下線（_）で強調箇所を囲む。
前後に空白がないと効かない場合がある。
```
ふつう**強調**ふつう
ふつう *italic* ふつう
```
ふつう**強調**ふつう
ふつう *italic* ふつう
### ★外部参照
```
リンク: [Google](https://www.google.co.jp/)
画像: 
```
リンク: [Google](https://www.google.co.jp/)
画像: 
多くの場合、単にURLを書いただけでもリンクにしてもらえる。
```
https://www.google.co.jp/
```
https://www.google.co.jp/
### ★表
```
| 左揃え | 中央揃え | 右揃え |
|:---|:---:|---:|
|1 |2 |3 |
|4 |5 |6 |
```
| 左揃え | 中央揃え | 右揃え |
|:---|:---:|---:|
|1 |2 |3 |
|4 |5 |6 |
> たとえデフォルトの左揃えでよくても、二行目の書式行を書かないと表にならない。
### ★HTML直か書き
一般にどのWikiTextでもそうだが、テキスト文中にHTMLを直接記述できる。
```
色を変えたければオレンジとすればよい。
ボタンを付けたければ:
```
色を変えたければオレンジとすればよい。
ボタンを付けたければ:
### ★参考サイト
- [Markdown記法 チートシート](https://gist.github.com/mignonstyle/083c9e1651d7734f84c99b8cf49d57fa)
> ほかにも「Markdown 文法」などと検索すればいろいろ出てくる。
### ★技術情報
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
- [CommonMark](https://commonmark.org/)
- [Pandoc](https://pandoc.org/)
- [markdown-it](https://github.com/markdown-it/markdown-it)
---
Presented by [Kobu.Com](https://kobu.com/)
2019/09/08 作成
2020/07/11 公開