Web.Tech

Markdown

2013年11月24日

業務上の設計書はWordやExcel、Powerpoint等で作成されています。プログラムコードや環境周りに関する情報は、テキストレベルでいいから少しでも書き残して欲しいものが多々あります。これが無くて苦労する事が実に多い。 納品ドキュメントではない情報は、基本的にテキストで良くないでしょうか？書くの簡単だし検索も楽！！

そのままバージョン管理システムに入れられるメリットもあるし、インターネットもLinuxもテキスト文化ですからね。

そこで！覚えておけばみんな幸せになれるかもしれないテキストドキュメント記法を勉強しました。
※この記事も勉強がてらMarkdownで作成しています。

Markdown記法とは

  • 文書を記述するための軽量マークアップ言語
  • 文章作成やメモ書きにも便利
  • 簡単なテキストをPandocを使えばHTML、Word、PDF等などへ変換できる
    • 文書をWebへ公開する事が簡単に行える。
    • インラインHTML HTMLを埋め込んでもそのまま動く(< → &lt; へ変換しない)
  • GitHubのREADMEやSNS、Blog、CMSのサービスで対応されているものが増えている
  • テキストと区別するために、拡張子は「.md」が良いらしい。
  • 利用サービスやツールによって方言がある(若干見栄えが異なる)
    • 削除線、アンダーラインが無い(HTMLで書けば解決)
    • 見やすいHTML文書とするには、CSSを作る必要があるかも。(特にコードの見栄え)

文書サンプル

#第◯回 ☓☓案件ミューティング議事録

* 日時: 2013/11/xx 10:00-11:00
* 場所: 都内某所◯◯ビル1F会議室
* 出席: ◯◯(記)、☓☓、△△(敬称略)

##議題
1. ◯◯について
    - △△の件
    - ☓☓の件
2. ☓☓の件

##◯◯について
本文*強調*本文

##☓☓の件
本文**強い強調**本文

##参考サイト
[Web.Tech](http://webdottech.github.io)

##次回開催予定
未定

注意事項

下記に記載したHTML変換結果についてはサンプルです。利用ツールによって結果が異なる可能性があります。

目次

記述方法

見出し(h1〜h6)

文頭に#

書き方

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

HTML変換結果

<h1>見出し1</h1>
<h2>見出し2</h2>
<h3>見出し3</h3>
<h4>見出し4</h4>
<h5>見出し5</h5>
<h6>見出し6</h6>

段落(p)

空行

書き方

あいうえお

かきくけこ

HTML変換結果

<p>あいうえお</p>  
<p>かきくけこ</p>

改行(br)

行末にスペース2つ

書き方

あい(半角スペース2つ)
うえお

HTML変換結果

あい<br />
うえお

段落中で強制改行する場合に使用。

強調

強調(em) イタリック

前後に * Or _

書き方

*強調*

HTML変換結果

<em>強調</em>

強い強調(strong) 太字

前後に ** Or __

書き方

**太字**

HTML変換結果

<strong>太字</strong>

2013/11/17時点 文中に使用する場合、前後にスペースが無いとKobitoで変換されない。

リスト

Disc型(ul>li)

文頭に * Or + Or -、後ろにスペース ※前後に空行が必要

書き方

* リスト1
* リスト2
* リスト3

HTML変換結果

<ul>
<li>リスト1</li>
<li>リスト2</li>
<li>リスト3</li>
</ul>

文頭に1つ以上スペースを入れることで入れ子が可能

書き方

* リストサンプル
    - ネストリストサンプル
        + ネストリストサンプル
    - ネストリストサンプル
* リストサンプル

Decimal型(ol>li)

文頭に「数字. 」、後ろにスペース ※前後に空行が必要

書き方

1. リスト1
2. リスト2
3. リスト3

※数字は連番でなくても良い(全て「1. 」も可)

HTML変換結果

<ol>
<li>リスト1</li>
<li>リスト2</li>
<li>リスト3</li>
</ol>

文頭に1つ以上のタブ Or スペースを入れることで入れ子が可能

書き方

1. リストサンプル
    1. ネストリストサンプル
        2. ネストリストサンプル
    2. ネストリストサンプル
1. リストサンプル

引用(blockquote)

文頭に > ※前後に空行が必要

書き方

>引用です
>引用です
>引用です

HTML変換結果

<blockquote>
<p>引用です 引用です 引用です</p>
</blockquote>

2個以上連続して書くことでネストが可能

書き方

>引用サンプル
>>引用サンプル
>>>引用サンプル

水平線(hr)

3つ以上の * Or - Or _　(半角スペースのみの行)

書き方

---

HTML変換結果

    <hr />

水平線サンプル

補足(以下のも水平線として扱われる)

* * *
--------------
**************
_________

リンク(a)

書き方

<URL>
[リンクテキスト](URL)
[リンクテキスト](URL "タイトル")

HTML変換結果

<a href="URL">URL</a>  
<a href="URL">リンクテキスト</a>
<a href="URL" title="タイトル">リンクテキスト</a>

mailto

書き方

<メールアドレス>

HTML変換結果

<a href="mailto:メールアドレス" title="mailto:メールアドレス">メールアドレス</a>

メールアドレスはロボット収集を欺くために16進数、10進数混在の数値文字参照に変換してくれる。

ページ内リンク

タグを埋め込めば可能

[リンクテキスト](#名前)

<a name="名前"></a>

定義参照リンク

文中に挿入するリンクを後でまとめて定義する。 注釈のような定義の仕方。文書の最後にURLをまとめて定義する事ができる。

■文中のリンク
[リンクテキスト][linkref]

■URL定義
[linkref]: URL "タイトル"
※段落外に記載すること

linkrefは大文字小文字の区別無し

書き方

本文に[リンク１][1]を挿入する
本文に[リンク２][2]を挿入する

[1]: URL1 "タイトル1"
[2]: URL2

HTML変換結果

本文に<a href="URL1" title="タイトル1">リンク</a>を挿入する
本文に<a href="URL2">リンク2</a>を挿入する

リンクテキストと同じ場合、linkrefは省略が可能

書き方

[google][]

[google]: http://www.google.co.jp

画像(img)

リンクの記法の頭に!を付けるだけで画像リンクとなる。 リンク(a)に記載の定義参照リンクも利用可能

書き方

![代替テキスト](画像のURL)
![代替テキスト](画像のURL "画像タイトル")

HTML変換結果

<img src="画像のURL" alt="代替テキスト" />
<img src="画像のURL" title="画像タイトル" alt="代替テキスト" />

表(table)

書き方

| Left align | Right align | Center align |
|:-----------|------------:|:------------:|
|Left        |Right        |Center        |
|Left        |Right        |Center        |

HTML変換結果

<table>
<thead>
<tr>
<th style="text-align: left">Left align</th>
<th style="text-align: right">Right align</th>
<th style="text-align: center">Center align</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">Left</td>
<td style="text-align: right">Right</td>
<td style="text-align: center">Center</td>
</tr>
<tr>
<td style="text-align: left">Left</td>
<td style="text-align: right">Right</td>
<td style="text-align: center">Center</td>
</tr>
</tbody>
</table>

コード

行頭に4つ以上のスペース Or タブ

書き方

System.out.println("Hello!World");

HTML変換結果

<pre><code>System.out.println("Hello!World");</code></pre>

コードの断片を記載する場合は `バッククオートで囲む

書き方

コードの中の`println`は`print`でも使えます。

HTML変換結果

コード中の<code>println</code>は<code>print</code>でも使えます。

シンタックスハイライト

バッククオート`３つのブロックで囲む

書き方

```java
System.out.println("hello");
```

１行目のjavaはコメント。用意されている言語とマッチするとそれ用のシンタックスハイライトに変換してくれる。

表示

System.out.println("hello");

拡張機能。対応していないツールもある。
CSSをpygmentizeで作成する等少し面倒。

$ sudo easy_install pygments
pygmentize -S default -f html > pygments.css

エスケープ

行頭にバックスラッシュ \ Or ¥

書き方

\#h1

HTML変換結果

#h1

参考サイト

ツール

  • MarkDown#Editor Markdownエディタ(Windows用)
  • MoU Markdownエディタ(Mac用)
  • kobito Mac用 MarkDownをプレビューできるエディタ(Qiitaのツール)
  • PanDoc MarkdownをHTMLやPDF、Word等へ変換
blog comments powered by Disqus