Markdown 記法

Philosophy - Markdownとは

Markdownとは、WEBページを記載する際に用いる、テキストをHTMLに変換する記法の一つです。
通常、WEBページはHTMLによって表記されますが、ブラウザからでなく通常のテキストエディタなどから見た時、HTMLは若干煩雑で全体像を把握し辛いのも事実です。

そこで、Markdown記法では、Settext, atx, Textile, reStructuredText, Grutatext, EtTeといったテキスト文書をHTMLに変換する既存の記法を参考にし、HTMLに変換しないままでも閲覧性に優れた表記方法を実現しています。
これは、何よりも電子メールで用いられる日常的な表現方法を参考にしているためです。
(英文メールで良く使われる表現方法である事に注意)

当ページでは、通常のMarkdownに加え、Markdown Extraで有効な表記方法についても解説も加えています。

このテキストは、もともとの解説文の意訳+私の個人的認識であり、間違っている箇所や解説が不足している箇所もあるかもしれません。
間違いを見つけた場合、当ページのForumにご連絡下さい。

Markdown 記法で書かれた書式説明文をダウンロード

Block Elements - ブロック要素

Paragraph - 段落

空行があれば、そこで段落が切り替わる。
改行(<br />)を入力する場合、改行をさせたい行の最後に２つ以上の空白(半角スペース)を入力する必要がある。
これを行わない場合、テキスト上で改行されていても<br />に変換されず、１行と見なされる。

Header - 見出し

見出しを表記するための記法は２種類ある。

１つは Setext 記法。
見出しにしたいテキストの下に、適当の数のイコール(=)かハイフン(-)を入力する。
"=" の場合大見出し(h1)、"-" の場合、中見出し(h2)で表示される。

This is an H1  
=============  
This is an H2  
-------------

This is an H1

This is an H2

もう１つの方法は atx 記法で、テキストの前にくるシャープ(#)の数で見出しの強さが変化する。

# This is an H1  
## This is an H2  
### This is an H3  
#### This is an H4  
##### This is an H5  
###### This is an H6

This is an H1

This is an H2

This is an H3

This is an H4

This is an H5
This is an H6

▲トップへ

ヘッダー属性

ヘッダ名を記述した行の最後に、空白を１文字以上あけて {} で囲むように id 名を指定すると、id 属性をつけることができる。

変換前：
# Header 1 {#header1}
変換後：
<h1 id="header1">Header 1</h1>

これを利用し、以下のようにページ内リンクを作ることができる。

[Link back to header 1](#header1)

▲トップへ

Blockquote - 引用

行頭に > があれば、引用文と見なされる。

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,  
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.  
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.  
>   
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse  
> id sem consectetuer libero luctus adipiscing.

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

全ての行頭でなくても、段落の先頭に > があった場合、その段落全体が引用文と見なされる。

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.  
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 
id sem consectetuer libero luctus adipiscing.

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

> を重ねて書くことで、引用を入れ子にできる。

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

引用中にほかの Markdown 記法を用いることもできる。

> ## これは見出し
> 
> 1.   これは１つ目のリストアイテム
> 2.   これは２つ目のリストアイテム
> 
> これはサンプルコードです。
> 
>     return shell_exec("echo $input | $markdown_script");

これは見出し

  1. これは１つ目のリストアイテム
  2. これは２つ目のリストアイテム

これはサンプルコードです。

return shell_exec("echo $input | $markdown_script");

▲トップへ

List - 箇条書き

番号なしの箇条書きや、番号付きの箇条書きも表示できる。

番号なしリスト

番号なしのリストには、アスタリスク(*)、プラス(+)、ハイフン(-)を用いることができる。
どれを使用してもかまわない。結果は同じとなる。

*   赤
+   緑
-   青
  • 赤
  • 緑
  • 青

番号付きリスト

番号付きリストには、「数字」とそれに続く「ピリオド(.)」を用いる。

1. Bird
2. McHale
3. Parish
  1. Bird
  2. McHale
  3. Parish

この際、番号付きリストであることを示すために使った「数字」は、実際の表示には何の影響も及ぼさないため、順番通りでなくてよい。

1. Bird
1. McHale
1. Parish
3. Bird
2. McHale
8. Parish
  1. Bird
  2. McHale
  3. Parish
  4. Bird
  5. McHale
  6. Parish

▲トップへ

リスト内記法

マーカーの後ろには１つ以上の空白かタブを入れる必要がある。
また、リストの各マーカーの後ろには最大３つまでの空白を入れ、インデントすることができる。
もちろん、しなくてもよい。

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.  
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,  
    viverra nec, fringilla in, laoreet vitae, risus.  
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.  
Suspendisse id sem consectetuer libero luctus adipiscing.
  • Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
  • Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

リストの途中で空行を入れると、リスト要素は段落化される。

*   Bird
*   Magic

  • Bird

  • Magic

リスト内の要素を段落化したい時は、空行を入れた後の段落の頭に４つの空白かタブを入れる。
行頭全てでなくてもよい。

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.  
(空行)  
    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.  
(空行)  
2.  Suspendisse id sem consectetuer libero luctus adipiscing.

  1. This is a list item with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

  2. Suspendisse id sem consectetuer libero luctus adipiscing.

*   This is a list item with two paragraphs.  
(空行)  
    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.  
(空行)  
*   Another item in the same list.

  • This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're only required to indent the first line. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

  • Another item in the same list.

リスト中に引用文を入れる場合、行頭の > をインデントする。
コードブロックを入れるなら、行頭に８つの空白か２つのタブを入れる。

*   A list item with a blockquote:  
(空行)  
    > This is a blockquote  
    > inside a list item.

  • A list item with a blockquote:

    This is a blockquote
    inside a list item.

*   A list item with a code block:  
(空行)  
        &lt;code goes here&gt;

  • A list item with a code block:

    &lt;code goes here&gt;

▲トップへ

定義リスト

定義項目の次の行にコロン(:)と１つ以上の空白をつけることで定義リストになる。

Apple  
:   Pomaceous fruit of plants of the genus Malus in 
the family Rosaceae.  
(空行)  
Orange  
:   The fruit of an evergreen tree of the genus Citrus.
Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
Orange
The fruit of an evergreen tree of the genus Citrus.

空行を挟むと、定義文(dd)内が段落となる。

Apple  
(空行)  
:   Pomaceous fruit of plants of the genus Malus in 
the family Rosaceae.  
(空行)  
Orange  
(空行)  
:    The fruit of an evergreen tree of the genus Citrus.
Apple

Pomaceous fruit of plants of the genus Malus in the family Rosaceae.

Orange

The fruit of an evergreen tree of the genus Citrus.

▲トップへ

Code Block - コードブロック

４つ以上の空白か１つのタブを行頭に入れることで、コードブロックになる。

p_blog では code タグのスタイルに { white-space: normal; } が指定されてしまっているため、コードブロック内での改行が反映されない。
コードブロック内で改行を行わせたい時は、スタイルシート内に以下の指定を追加するとよいだろう。

pre code {
    white-space: pre;
}


This is a normal paragraph:  
    This is a code block.

This is a normal paragraph:

This is a code block.

コードブロックはインデントのない行か文書の終わりまで続く。

Here is an example of AppleScript:  
    tell application "Foo"  
        beep  
    end tell

Here is an example of AppleScript:

tell application "Foo"  
    beep  
end tell

コードブロック中では、アンパサンド(&)やブラケット(<>)は HTML エンティティに変換される。
また、コードブロック中では Markdown 記法は無効となる。

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>


<div class="footer">
    &copy; 2004 Foo Corporation
</div>

▲トップへ

Horizontal Rule - 区切り線

ハイフン(-)、アスタリスク(*)、アンダースコア(_)のどれかを３つ以上書いた行は、区切り線に変換される。
間に空白が入っていてもよい。ハイフンは見出しに解釈されることもあるため、前後には空行を入れた方がよい。

* * *
***
*****
- - -
---------------------------------------
_ _ _

Span Elements - インライン要素

Link - リンク

インラインとリファレンスの２つのやり方がある。
インラインでは、文中にリンクを [] と () で記載する。[] 内にはリンクテキスト、() 内にはリンク先の URI が入る。

This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.

This is an example inline link.

This link has no title attribute.

ローカルなリソースにリンクを張ることもできる。

See my [About](/about/) page for details.

リファレンススタイルでの記述は、２組の [] を用いる。前の [] にはリンクテキスト、後の [] には id が入る。

This is [an example][id] reference-style link.
This is [an example] [id2] reference-style link.

その後、文書内のどこかに id の実際の参照先を記す必要がある。
URI は <> で囲んでもよい。

[id]: http://example.com/  "Optional Title Here"
[id2]: <http://example.net/>  "Optional Title Here"

URI の後の " " 内に書かれたテキストは、タイトル属性に適用される。
URI が長い時は、タイトル属性を次の行に書ける。この際、タイトル要素を記述する行の先頭には空白かタブを入力する。

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

また、id は大文字小文字を区別しない。
リンクテキスト = id で問題ない時は、id 欄に何も入れる必要はない。

[Google][]
[Google]: http://google.com/

文章中にリンクが多くなる場合、インラインスタイルよりもリファレンススタイルで記述した方が見通しがよくなる。

▲トップへ

Emphasis - 強調

テキストを、アスタリスク(*)かアンダースコア(_)で囲むことで強調表示させることができる。
それぞれ１つで em、２つで strong タグに変換される。

*single asterisks*
_single underscores_
**double asterisks**
__double underscores__

single asterisks

single underscores

double asterisks

double underscores

単語の途中で囲んでも強調は適用される。
* _ が空白で囲まれている時は、そのまま * _ が表示される。
* _ で囲んでも強調表示させたくない場合は、バックスラッシュ()で回避することができる。

un*fucking*believable
\*this text is surrounded by literal asterisks\*

unfuckingbelievable

*this text is surrounded by literal asterisks*

強調に関する補足

I like it when you say _you love me_.
Please open the folder "secret_magic_box".

上の行のようにアンダーバーで囲んだ部分は強調されてしまうが、下の行のようにリテラル文字列のような形式で記載してあれば、変換されることはない。

▲トップへ

Code - コード

インラインのコードスタイルを使用する時は、バックチッククォート(`)で囲む。
コードスタイル内でバックチッククォートを使用する時は、`` で囲む。

Use the `printf()` function.

Use the printf() function.

デリミター(区切り符号)の周りに空白がある時は、その空白も含めてデリミターとなる。

A single backtick in a code span: `` ` ``
A backtick-delimited string in a code span: `` `foo` ``
``There is a literal backtick (`) here.``

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

There is a literal backtick (`) here.

コードスタイル中では、アンパサンド(&)やブラケット(<>)は HTML エンティティに変換される。

`&#8212;` is the decimal-encoded equivalent of `&mdash;`.

&#8212; is the decimal-encoded equivalent of &mdash;.

▲トップへ

Image - 画像

リンク文法の頭にエクスクラメーション(!)をつけることで、埋め込み画像に変換される。
インラインでもリファレンスでもかまわないが、画像の細かい要素(サイズなど)を指定することはできない。

![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")
![Alt text][id]
[id]: url/to/image  "Optional title attribute"

▲トップへ

Tables - テーブル

ハイフン(-)とパイプ(|)を利用してテーブルを生成することができる。
ハイフンで区切ると、上が thead、下が tbody に格納される。それらの区別は、ハイフンとパイプがそれぞれ１つ以上あればよい。

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell
First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

ハイフンの後にコロンを入れることで、列全体を寄せることができる。
右端に入れれば右に、左端に入れれば左に、両端に入れれば中央に寄る。

Item      | Value
--------- | -----:
Computer  | $1600
Phone     |   $12
Pipe      |    $1
Item Value
Computer $1600
Phone $12
Pipe $1

もちろん、テーブル内のテキストに Markdown 記法を用いることも可能。
両端のパイプはあってもなくてもよい。

| Function name | Description                    |
| ------------- | ------------------------------ |
| `help()`      | Display the help window.       |
| `destroy()`   | **Destroy your computer!**     |
Function name Description
help() Display the help window.
destroy() Destroy your computer!

▲トップへ

Miscelleneous - その他の要素

Automatic Link - 自動リンク

ブラケット(<>)で囲むと自動リンクになる。

<http://example.com/>

これは、以下の記述と同じ結果になる。

[http://example.com/](http://example.com/)

メールアドレスをブラケットで囲むと、スパム対策としてエンティティに変換してくれる。

<address@example.com>

address@example.com

▲トップへ

Backslash Escape - エスケープ

\ を使うことで、Markdown 記法に用いられる各種文字をエスケープすることができる。
エスケープされる文字は以下の通り。

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark
:  colon
| pipe

▲トップへ

Markdown Inside HTML Blocks - ブロック要素内での Markdown

Markdown 記法の文書内に通常の HTML タグを記載した場合、その箇所は変換を行わず、記載されたままの HTML を表示する。
タグ以外の部分は Markdown の文法に従って変換が行われるが、一部のブロック要素を記載した場合、その要素内では Markdown による変換が無効となる。
そういったタグ内でも Markdown を利用したい場合、ブロック要素の属性に markdown="1" と記載する必要がある。

<div markdown="1">
This is *true* markdown text.
</div>

This is true markdown text.

このとき、markdown 属性が適用されたタグ内に適さない要素があった場合、それらを変換はしない。
例えば <p> タグ内にあるリストや引用、コードブロックなど。<p> タグ内では markdown 属性が設定されても、インライン要素しか変換を行わない。
ただし、以下のように曖昧なケースがいくつかある。

<table>
<tr>
<td markdown="1">This is *true* markdown text.</td>
</tr>
</table>

テーブルセル(<td>)では、インラインとブロックの両方の要素を含むことができる。
このような場合にブロック要素の変換を許可するには markdown="block" と書く必要がある。

▲トップへ

ADMIN PANEL