Markdown文法の全訳

2310 — Thu, 29 May 2008 21:00:00 +0000

Markdownの文法について作者が解説したページを全訳してみました。まだまだ手を入れ足りないところがありますが暫定公開します。

【更新】2008年12月30日17時45分(ホームページを移動)

【原文】http://daringfireball.net/projects/markdown/syntax.php

【ＨＰ】http://daringfireball.net/projects/markdown/

原文のライセンス表示

はじめに

注意

ライセンスは修正BSDライセンスです。原文のライセンスを尊重の上、適当にどうぞ。
意訳していて、原文の意味を損なわない程度に言葉を加えたり省略している部分があります。
訳が間違っている可能性があります。暫時修正はするつもりですが、必ず原文を優先するようにしてください。
意見等につきましては遠くない将来にコメント欄など何らかの連絡方法を保てるようにしたいと考えています。

おまけ

この解説ページそのものもMarkdownにより文章を作成しています。私も使いこなせているとは言えないかもしれませんが、とりあえずMarkdownルールに従って書いたこのページの原稿を置いておきます。参考程度にどうぞ。

お詫び

Markdownの不具合というよりは日本語環境下で使用する上での問題ですが、 Shift_JISのテキストをMarkdownで変換すると不具合が発生する可能性があります。これは円記号問題に由来し、例えば「(表)」と本文に書くと、Markdownは「(X\)」(Xはコード数値)と理解する場合があるようです。

このページそのものは以前はEUC-JPで、現在はUTF-8で記述しています。しかし配布していたmarkdown-sample.txtはShift_JISに変換したものでした。こちらでチェックしたところ、Linux上のUTF-8環境下で一部の文字化けを確認しました。ご迷惑をおかけました。

改めてサンプルをEUC-JPとしたものを、変換結果のHTMLと併せzipで圧縮したものを配布します。

markdown_sample_20061231.zip (約24KB)

追記

とりあえずMarkdown.plを変更してShift_JISに対応できるように試験中です。以下に変更処理済みのMarkdown.plを含めたサンプルを置いておきます。配布している中のsample.txt及びsample.htmlはShift_JISになっています。Linux環境下でしか試していませんので不具合があるかもしれません。

Shift_JISの場合は文字コードを一回UTF-8に変換してから実行(したがって遅くなります)
改行コードを変更しない(オリジナルは\nに統一してしまうようなので)
PHPタグサポート(本文のPHPスクリプトタグを参照)
Styleタグサポート(本文のStyle – スタイルタグを参照)

以下からダウンロードしてください。Perl5.8.0以上かもしくはJcode.pmが必要です。

markdown_sample_patched_20070102.zip(約42KB)

Index - 目次

Overview - 概要

Philosophy - Markdownとは
Inline HTML - 文中にHTMLソースを直接記述したい
Automatic Escaping for Special Characters - 特殊記号の自動処理

Block Elements - 範囲を構成する

Paragraphs and Line Breaks - 段落と改行、MovableTypeとの比較
Headers - 見出し
Blockquotes – 引用
Lists – リスト
Code Blocks – ソースコードを表現
Horizontal Rules – 罫線

Span Elements – 文中の変換

Links – リンク
Emphasis – 強調
Code -ソースコードの記述
Images – 画像

Miscellaneous – その他様々なこと

Automatic Links – 自動リンク
Backslash Escapes – バックスラッシュ(円記号)による変換回避

Overview - 概要

Philosophy - Markdownとは

Markdownは可能な限り簡単に読み書きできるようにしたものです。

Markdownのルールで書かれたテキストはタグなど複雑な要素が用いられていないため直感的に分かりやすく、HTMLに変換しないままでも配布することが可能です。 MarkdownのルールはSettext、 atx、 Textile、 reStructuredText、 Grutatext、 EtTeといったテキスト文書をHTMLに変換するツールを参考にしています。しかし、何よりメールで用いられている表現を参考にしています。

最後に、Markdownのルールは、ハイフンやセミコロンといった記号を使用しています。これらの記号は、それを実際に使用した効果を考え選び抜かれているものです。例えばMarkdownでも(メールなどと同様)単語をアスタリスク(*)で囲むと*強調*となります (2310注：英文メールではアスタリスクが強調に用いられるらしいです。ewomanの「英文メール入門」とか参照してください)。リストは、そう、リストのままです。 Markdownの引用のルールも引用記号を使用したものです。これらは普段メールで使われている方法です。

目次へ

Inline HTML - 文中にHTMLソースを直接記述したい

Markdownのルールの目的はただ一つ。ホームページを「書く」ことです。

MarkdownはHTMLタグの代わりになるものではありませんし、 HTMLタグで表現できるレベルにも達していません。 Markdownはホームページを表現するルールとしては限定されたものであり、HTMLタグで可能な表現を一部実現しているだけです。 HTMLタグを簡単に扱えるようにしたものでもありません。そもそもHTMLタグは既に扱いやすいものとなっています。 Markdownのルールのコンセプトは原文のままで読みやすく、書きやすく、編集できることです。 HTMLタグルールはホームページを作成するためのルールですが、Markdownは書きやすくするためのルールなのです。だからMarkdownはテキストとして書かれ表現できる範囲でホームページに変換するものです。

Markdownのルールでは変換されない部分については素直にHTMLタグを使用してください。 MarkdownからHTMLへと切り替えるために何かする必要はありません。ただHTMLタグを記述すれば良いのです。

唯一、

、、

、

などブロックタグを使用するときにはルールがあります。これらのタグで囲まれた前後は空行でなければいけません。さらに、これらのタグは行頭に置かなければなりません。タグの前にスペースやタブを記入しないでください。これらのブロックタグにMarkdown余分な

タグを挿入しません。

例えばMarkdownのルールで書かれた文書にtable(表)を加えるのは以下、

This is a regular paragraph.

Foo



This is another regular paragraph.

Markdownの記述ルールがこうしたブロックタグの中では有効とならないことに注意してください。例えばMarkdownの記述ルール、*強調*はHTMLタグの中では使用できません。

、、もしくはといったspanレベルのタグについてはMarkdown文書の中ではどこでも使用することができます。リストの項目の中でもヘッダでもかまいません。もし望むならMarkdownの記述ルールの代わりにHTMLタグを直接使用することもできます。例えば、Markdownの記述の中やタグを直接使用したければでそうしてください。正しく動作します。

ブロックタグとは異り、spanレベルのタグの中ではMarkdownのルールは有効となります。

目次へ

Automatic Escaping for Special Characters - 特殊記号の自動処理

HTMLでは特別に処理される文字が二つあります。<と&です。 <はタグ記述の開始として処理されます。 &はHTMLで特殊記号を表現するのに使用します。もしこれらをそのまま表現したい場合は、<、&とHTMLのルールに従って記述しなければなりません。

アンパサンド(&)は特にWEB製作者を混乱させます。もしAT&Tを表示しようと思ったら、AT&Tと書かなければいけません。さらにURLの中でアンパサンド(&)が使用されていると、それも修正しなければいけません。つまり、もし以下のURLをリンクとして表示させたければ

http://images.google.com/images?num=30&q=larry+bird

このように修正しなければいけません。

http://images.google.com/images?num=30&q=larry+bird

href属性についてのこのルールはこれは非常に忘れやすく、おそらく他はHTML 文法に忠実であっても唯一これだけは誤ってしまっているHTMLページが多いでしょう。

Markdownでは、これらの特殊文字処理を自動的に変換することでこれらの文字(記号)を自然に使用することができるようになっています。もしアンパサンド(&)が文章の一部として使用された場合は変換されずにそのまま、そうでなければ&に自動的に変換されます。

したがって、もしコピーライト表示を行いたい場合は次のように書くことができます。

©

これについてはMarkdownはそのままにしておくでしょう。しかし、もし以下のように書かれていた場合、

AT&T

Markdownは下のように変換します。

AT&T

同様にMarkdownはインラインHTMLをサポートしますので、もしアングル・ブラケット(<と>)が HTMLタグとして記述されていれば、MarkdownはHTMLタグとして認識します。しかし、もし以下のように書かれていれば、

4 < 5

Markdownは以下のように変換します。

4 < 5

しかしながら、Markdownのコードスパンやブロックの中では、アングル・ブラケットやアンパサンドは常に自動的に変換処理されます。これによって、Markdownを使用してHTMLコードそのものを記述することができるのです。 (これはHTMLソースコードを直接記述するのとは対照的です。HTMLソースコードを使用して、HTMLソースコードのことを説明するホームページを作成しようと思うとひどく見にくいソースコードになります。これはサンプルのHTMLソースコード中の<や&をいちいち特殊記号に置き換えなければならないからです。)

目次へ

Block Elements - 範囲を構成する

Paragraphs and Line Breaks - 段落と改行、MovableTypeとの比較

空白行に囲まれた複数行の文章(一行の場合も含む)がまとめて一つの段落として扱われます。 (ここで言う空白行とは空白に見える行のことです。スペースやタブだけの行も空白行に含まれます。) 通常段落の行頭にスペースやタブがあってはいけません。

「一行以上に渡って連続した」という言葉が意味するのはMarkdownが改行された文章も一つの段落としてサポートするということです。これは他のテキストからHTMLへの変換ツールとの明確な違いとなります。例えばMovableTypeの編集の際にはデフォルトで「Convert Line Breaks」という機能を使用することができますが、これは原文の改行をそのまま
タグに置き換えます。

Markdownで
タグを使用したい時は、その行の末尾を二つ以上のスペースを記述してから改行することとなります。

これは意図的に
を使用する場合には多少の努力が必要であることを示しています。全ての(原文での)改行は
であるという単純なルールをMarkdownは用いていないのです。しかし、それによって、Eメールで使用するような引用や、複数の段落で構成されるリストなどは、原文で改行するよりは見栄えがよくなります。

目次へ

Headers - 見出し

MarkdowwnはSetextとatxという、二つの形式をサポートしています。

Setext形式の見出しは、第一レベルの見出しに’='、次レベルの見出しに’-'をアンダーラインとして用います。例えば、

This is an H1
=============

This is an H2
-------------

アンダーラインで用いられている’='や’-'の数は見出しの長さと一致する必要はありません。いくつであっても動作します。

Atx形式は見出しの行頭に1つから6つまでの#(ハッシュ記号)を用いる方法です。#(ハッシュ記号)の数が見出しレベルと一致します。例えば

# This is an H1


## This is an H2

###### This is an H6

Markdown独自の機能として、atx形式を「閉じる」ことができます。この表現が好みであれば使うことができますが、単純に見栄えの問題です。行末の#(ハッシュ記号)の数は行頭と一致する必要もありません。

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

目次へ

Blockquotes – 引用

Markdownで引用を表現するときにはEメールと同じ方法、>を用います。もしあなたがEメールで引用をすることになじんでいるのであればMarkdownでの使用は容易です。あなたは既にルールを知っています。改行した各行の冒頭に>をつけるだけです。

> 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.

Markdownでは段落の冒頭に>をつけるだけでも良く、編集時の負担を軽減することができます。

> 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.

引用の中はMarkdownのルールで記述してかまいません。見出しももリストも認識します。

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

テキストエディタの中にはEメールで使用する引用スタイルを簡単に作成することができるものがあり、それらを活用できます。例えばMac用のエディタBBEditは引用符付き貼り付けをすることができます。(2310注：BBEdit以外についてはgoogleで検索でもしてください)。

目次へ

Lists – リスト

Markdownは冒頭に番号付きや印付きのリストをサポートしています。

印付きのリストの場合はアスタリスクやプラス記号、それにハイフン記号を使用します (2310注:記号の直後にスペースかタブが無ければいけない〜後述)。これらは自由に使いわけることが可能です。

*   Red
*   Green
*   Blue

は以下と同じ意味となります。

+   Red
+   Green
+   Blue

や

-   Red
-   Green
-   Blue

番号付きリストはピリオドつきの番号を用います。

1.  Bird
2.  McHale
3.  Parish

HTMLに変換される時には、リストを記述する際に使用した番号が無視されることに注意してください。上の例文は以下のようなHTMLに変換されるからです。


Bird
McHale
Parish

したがってもし代わりに以下のように記述してMarkdownで変換しても

1.  Bird
1.  McHale
1.  Parish

あるいは以下であっても

3. Bird
1. McHale
8. Parish

出力されるHTMLの構文は同じです。つまり、出力されるHTMLと揃えたいのであれば一致するように番号を振れば良いし、そうでなければ揃える必要は無いということです。

ただ、番号付リストを使用する際には1からはじまるように書いた方が良いでしょう。 Markdownが将来、リストに自由な数字から番号をスタートできるような機能をサポートするかもしれないからです。

リストの番号もしくは記号は通常左端からはじまりますが、冒頭に3つのスペースまでは許されています。またリストの番号もしくは記号の後には1つ以上のスペースか、タブが挿入されていなければいけません。

リストを綺麗に見せるために、リストの内容の二行目以降を揃えることができます。

*   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.

もし各リストの間に空行があると、Markdownは各々のリストの内容を

タグで囲みます。例えば以下のように記入します。

*   Bird
*   Magic

これは以下のように変換されるはずです。


Bird
Magic

しかしこれは

*   Bird

*   Magic

このように変換されます。


Bird
Magic

各々のリストの中にはさらにいくつかの段落がある場合があります。このような段落(の少くとも冒頭)は行頭から4つのスペース分離れているか、もしくはタブが一つなければなりません。

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.

リストの中に引用を配置することもできます。引用で使用する>記号の前も同様に4つのスペースかタブを一つ入れてください。

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

また、リストの中にコードを配置するためには、インデントの量を2倍、すなわち8スペースか2タブ分行頭になければいけません。

*   A list item with a code block:



その気はなくても、書いているうちに偶然リストになってしまうこともあるでしょう。

1986. What a great season.


行頭で数字の直後にピリオドを用いると(MarkDownの構文と解釈され)このような事態が生じます。
これを避けるためにはピリオドの前にバックスラッシュ(日本のOS、
Windowsでは円記号)をピリオドの前に記述してください。

1986\. What a great season.


目次へ

Code Blocks – ソースコードを表現

HTMLやプログラムのソースコードなどをそのままホームページに表示したい場合です。
これらが書かれた範囲は、通常の文章による段落とは異り書かれたとおりに解釈されることになります。
Markdownはこれらの変換に
タグとタグの両方を使用します。

Markdown上でコードブロックを書くには単純に各行の冒頭に4つ以上のスペースもしくは1つ以上のタブを挿入してください。以下の例を見てください。

This is a normal paragraph:

    This is a code block.


Markdownで変換するとこうなります。

This is a normal paragraph:

This is a code block.



各行の最初の4スペースもしくは1タブは変換後は除去されます。例えば、以下。

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でHTMLソースそのものをホームページとしたい場合は、貼りつけてインデントすればいいだけとなります。
Markdownはアンバサンド記号(&)やアングル記号(<と>)のencodingによる不具合を自動的に回避します。

例えば以下、


    © 2004 Foo Corporation



これは次のように変換されます。

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



通常Markdownの記述ルールはコードブロックの中では有効となりません。
例えば(Markdownでは強調時に使用する)アスタリクス記号(*)はコードブロックの内部ではあくまで*のままです。
つまり、コードブロック内でMarkdownの記述ルールそのものについて容易に書いて使用することができるわけです。

目次へ

Horizontal Rules – 罫線

3つ以上のハイフン(‘-’)やアスタリスク(‘*’)、アンダースコア(‘_’)だけで構成されている行は罫線
となります。
また、これらの記号の間には半角スペースを用いることができます。以下のどの行も罫線に変換されます。

* * *

***

*****

- - -

---------------------------------------

_ _ _


Span Elements – 文中の変換

Links – リンク

Markdownは直接リンクと参照リンクの二つをサポートしています。
どちらについても、リンクしたい文字列を角カッコ-’['と']‘-で囲みます。

直接リンクを作成するためには、角カッコで囲んだリンク文字列の直後
に丸括弧-’(‘と’)'-を設置します。丸括弧の内部では、リンク先のURLをを記
述してください。”で囲むことによってマウスカーソルをリンクにあてると表
示されるリンク先のタイトルを追加することも可能です。例えば、

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] [id] reference-style link.


それから、文中のどこでも良いので、このIDに対するリンクを以下のように設定します。

[id]: http://example.com/  "Optional Title Here"


これは、


リンクIDを角カッコで囲んだものである(左からスペース3つ分までインデントすることができる)
上の後にはダブルコロン(‘:’)が続く
その後一つ以上のスペースか、タブが続く
その後にリンク先のURLが続く
その後にリンクのタイトル属性をシングルかダブルクオンテーションで囲んだ状態で追加しても良い


リンクURLはアングルブラケット(‘<’と’>')で囲むことができます。

[id]:   "Optional Title Here"


上のリンク定義はMarkdownがリンクを作成するために使用するだけです。変換後のHTML本文には表示されません。

リンクIDは文字でも数字、スペース、記号が入っていてかまいませんが、英文字の大文字小文字は区別されません。
例えば次の二つ、

[link text][a]
[link text][A]


これは同じものとなります。

暗黙リンクのルールを使用すれば、本文中にリンクIDを書く必要はありません。
この場合はリンク対象文字列がそのままリンクIDとして用いられます。
暗黙リンクのルールを使用するために、リンクIDは記入しないで空の角カッコを用いてください。

例えばGoogleという言葉をgoogle.comにリンクさせるためにはあなたはただこのように書けば良いことになります。

[Google][]


それから別の場所でこのリンクの定義をします。

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


リンク文字列にはスペースを含んでかまわないため、複数の単語で構成されている場合でも同様に扱うことができます。

Visit [Daring Fireball][] for more information.


このリンクの定義は以下となります。

[Daring Fireball]: http://daringfireball.net/


リンクの定義はMarkdownルールで書かれた文書のどこに位置していてもかまいません。
作者はリンクを設定した段落の直後に記述するのを好みますが、文書の一番最後にまとめて
配置することも可能です。

以下は実際の例です

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"


暗黙リンクのルールを用いてかわりに下のように書くことも可能です。

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"


上の二つの例はどちらも次のようなHTMLに変換されます。

I get 10 times more traffic from Google than from
Yahoo
or MSN.


比較のために同じ段落をインラインリンクのスタイルで書いたものを揚げます。

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").


参照スタイルの利点は書きやすさではありません。
参照スタイルの利点は文書がとても読みやすくなることです。
上に揚げた例を比べてください。リンクの参照スタイルを用いた場合、段落はたった81文字です。
しかしインラインスタイルを用いた場合は176文字になります。
さらにHTMLソースコードの段階では234文字となります。HTMLソースコードでは原文よりもマークアップされています。

Markdownのリンクの参照スタイルを用いると、原文はブラウザで表示されるも
のにより近くなります。段落外にリンクのためのデータを追いやることによっ
て、文章の流れを邪魔することなくリンクを追加することができます。

目次へ

Emphasis – 強調

Markdownではアスタリスク(*)やアンダースコア(_)は強調記号として扱われます。
1つの*や_によって囲まれた文字列は、タグで囲まれたものに変換され、
二つの*や_によって囲まれた文字列は、タグで囲まれたものに変換されます。


例えば以下のように記述します。

*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\*


目次へ

Code -ソースコードの記述

ソースコードの断片を記述するためには、バック・クォート(`)で囲みます。
ソースコードのブロックとは異なって、コードの断片の記述は通常の段落内で行います。
例えば、

Use the `printf()` function.


これは以下のように変換されます。

Use the printf() function.


コードの中でバック・クォートを文字として表現したい場合ために、囲むバック・クォートを複数とすることができます。

``There is a literal backtick (`) here.``


これは次のように変換されます。

There is a literal backtick (`) here.


バック・クォートで囲む内側、最初のバック・クォートの直後と最後のバック・クォートの直前にはスペースがあってかまいません。
これによって、囲まれたバッククォートの最初もしくは最後に文字としてバッククォートを扱うことできます。

A single backtick in a code span: `` ` ``

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


これらは次のように変換されます。

A single backtick in a code span: `

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


コード記述の中ではアンバサンドやアングル・ブラケットはホームページで表現できるように自動的に変換されます。
そのためHTMLのソースコードのサンプルを記述することが簡単となります。
マークダウンは以下の記述を

Please don't use any `` tags.


以下に変換します。

Please don't use any <blink> tags.


またこのように書くこともできます。

`—` is the decimal-encoded equivalent of `—`.


このように変換されます。

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


目次へ

Images – 画像

原文となるテキスト文書の中に画像を置くための「自然な」ルールを考えることは困難です。

Markdownは画像に関するルールをリンクに関するルールに近い形で扱います。
つまり、直接と参照という二つの形式をサポートします。

画像の直接リンクの方法は以下のとおりです。

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")


つまり、


一つのビックリマーク(!)が配置してあって…
角カッコが続きます。この角カッコは、画像の代替テキストを含んでいます。
さらに画像のURLやパスを囲んだ丸カッコが続きます。後ろにシングルかもしくはダブル・クオンテーションで囲んだタイトルを追加してもかまいません。


参照式では画像のルールは以下のようになります。

![Alt text][id]


idは定められた画像の参照を示すものです。
画像の参照はリンクの場合と同様な定義によって定義されます。

[id]: url/to/image  "Optional title attribute"


現在、Markdownでは画像リンクの際に大きさを指定できません。
もし使用したい場合はタグを直接使用してください。

目次へ

Miscellaneous – その他様々なこと

Automatic Links – 自動リンク

MarkdownはURLやメールアドレスへの自動リンクをサポートしています。
URLやメールアドレスをアングル・ブランケット(‘<’と’>')で囲むだけです。
つまり、もしURLやメールアドレスを表示して、かつそれがクリックするとリンクするようにするのは
あなたはこう書けば良いのです。




Markdownはこれを下のように変換します。

http://example.com/


メールアドレスの自動リンクも同様です。
ただしMarkdownはこの場合、メールアドレスをメールアドレス収集スパムボットから隠蔽するために
ランダムな10進法もしくは16進法を構成します。
例えばMarkdownは以下について、

 


このような形で変換します。

address@exa
mple.com


ブラウザでは、address@example.comが表示され、リンクになっているはずです。

(このエンコードトリックはほとんど、とは言わないまでも多くのアドレス収集ロボットを欺くことができます。
しかし、ロボットの全てではありません。何もやらないよりはましという程度です。
公開されたメールアドレスは何かのきっかけでスパムが届きはじめるものです。)

目次へ

Backslash Escapes – バックスラッシュ(円記号)による変換回避

Markdownのルール上特別の意味を持つ記号や文字をそのまま表現する場合にバックスラッシュ(円記号)を使用することによって回避できます。
例えば、もしアスタリスクを強調(HTMLのタグを使用)させるのではなく、そのままアスタリスクを表示したい場合は、
以下のようにアスタリスクの前にバックスラッシュ(円記号)を記述します。


\*literal asterisks\*


Markdownでは以下の文字について、バックスラッシュ(円記号)による変換処理の回避が可能です。

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


目次へ

2310による補足(原文には記述されていません)

原文で書かれていないことなどを補足しておきます。

コメントタグ

原文では触れられていませんが、ソースコードを見るとMarkdownはコメントタグも解釈するようです。

サンプルサンプル


というように一行の中にコメントが含まれる場合は、

サンプルサンプル


と変換されます。

しかし、複数行にわたるコメントの場合、

サンプル



は

サンプル



と変換されますが、コメント行に空白行を含めた場合、

サンプル



は

サンプル



と変換されてしまいます。コメント行に空白行を含めたい場合は、

サンプル



サンプル


と、コメント全体を独立させて前後に空白行を置いてください。意図したとおりに変換されます。

サンプル



サンプル


目次へ

PHPスクリプトタグ

Markdownは’’を
コメントタグと同様に扱いたい場合はMarkdown.plを「メモ帳」などのテキストエディタ
から編集しなければなりません。

以下は’’をコメントタグと同様に扱うためにソースコードに追加する例です。
右端に+がある行が追加する部分です。使用する場合は自己責任でお願いします。

## 738行目付近から
    # Special case for standalone HTML comments:
    $text =~ s{
                (?:
                    (?<=\n\n)       # Starting after a blank line
                    |               # or
                    \A\n?           # the beginning of the doc
                )
                (                       # save in $1
                    [ ]{0,$less_than_tab}
                    (?s:
                        
                    )
                    [ \t]*
                    (?=\n{2,}|\Z)       # followed by a blank line or end of document
                )
            }{
                my $key = md5_hex($1);
                $g_html_blocks{$key} = $1;
                "\n\n" . $key . "\n\n";
            }egx;

+   # Special case for PHP block:
+   $text =~ s{
+               (?:
+                   (?<=\n\n)       # Starting after a blank line
+                   |               # or
+                   \A\n?           # the beginning of the doc
+               )
+               (                       # save in $1
+                   [ ]{0,$less_than_tab}
+                   (?s:
+                       <\?
+                       (php.*?\?)+
+                       >
+                   )
+                   [ \t]*
+                   (?=\n{2,}|\Z)       # followed by a blank line or end of document
+               )
+           }{
+               my $key = md5_hex($1);
+               $g_html_blocks{$key} = $1;
+               "\n\n" . $key . "\n\n";
+           }egx;

    return $text;
}


目次へ

Style – スタイルタグ



本文・・・・・・・・


これを有効にするのはMarkdown.plをいじらなければなりません。324行目あたりにある、

my $block_tags_a = qr/p|div|h[1-6]|blockquote|pre|......|fieldset|iframe|math|ins|del/;
my $block_tags_b = qr/p|div|h[1-6]|blockquote|pre|......|fieldset|iframe|math/;


にstyleを加えて、

my $block_tags_a = qr/p|div|h[1-6]|blockquote|pre|......|fieldset|style|iframe|math|ins|del/;
my $block_tags_b = qr/p|div|h[1-6]|blockquote|pre|......|fieldset|style|iframe|math/;


とします。

目次へ

blog::2310 » Markdown

EmacsでもMarkdown

Markdown文法の全訳

原文のライセンス表示

はじめに

注意

おまけ

お詫び

追記

Index - 目次

Overview - 概要

Block Elements - 範囲を構成する

Span Elements – 文中の変換

Miscellaneous – その他様々なこと

2310による補足(原文には記述されていません)

Overview - 概要

Philosophy - Markdownとは

Inline HTML - 文中にHTMLソースを直接記述したい

Automatic Escaping for Special Characters - 特殊記号の自動処理

Block Elements - 範囲を構成する

Paragraphs and Line Breaks - 段落と改行、MovableTypeとの比較

Headers - 見出し

Blockquotes – 引用

Lists – リスト

Code Blocks – ソースコードを表現

Horizontal Rules – 罫線

Span Elements – 文中の変換

Links – リンク

Emphasis – 強調

Code -ソースコードの記述

Images – 画像

Miscellaneous – その他様々なこと

Automatic Links – 自動リンク

Backslash Escapes – バックスラッシュ(円記号)による変換回避

2310による補足(原文には記述されていません)

コメントタグ

PHPスクリプトタグ

Style – スタイルタグ