#markdown 記法の説明
ここでは Markdown 記法の概略を説明します。より詳細な情報は、 Markdown web site をご覧下さい。
em と strong
このようにすると em でマークアップされます。あるいはこれでも em です。
これは strong でマークアップされます。こうしても strong です。
このようにはしてはいけません。斜体で太字の文字列 になるように見えますが、マークアップの意味が可笑しくなります。これも同様です。
訳者:kyorecoba注 - この項の原文は根本的に誤っているので訂正して訳しました。"em" , "strong" がそれぞれ斜体・太字となるかはスタイル指定に依ります。
リンクアンカー
単純なリンクアンカー
３通りの記法があります。後になるにつれ、だんだん読みやすくなります。
リンクアンカーの href 属性の定義文字列は同じテキスト内のどこにでも配置できます。リンクアンカーよりも前でも後ろにまとめても構いません。
リンクアンカーとなる文字列は同じテキスト内でユニークであれば良く、大文字小文字を区別しません。[Yahoo!] と書くべきところを [YAHOO!] と書いてもかまいません。
title 属性つきのリンクアンカー
リンクアンカーには title 属性を入れることができ、これによって閲覧者はマウスポインタをリンクアンカー文字列に合わせるとツールチップでリンク先の情報を知ることができます。
リンクアンカーとなる文字列でリンク先の情報を十分に伝え切れない場合などは、title 属性を入れることは親切なものです。 (参照リンクでは、引用符の代わりに title 属性のための括弧が使用されます。)
- title 属性を付けた こちら というような貧弱な文字列によるリンクアンカー
- "こちらをクリック" なんて絶対書いてはいけません、本来は…。
- 私を信じてクリックして これもダメダメ
URL 文字列によるリンクアンカー
URL 文字列をそのままリンクアンカーにしたい場合、前後を < と > で括ります。 - 私のサイト URL は http://www.attacklab.net です。
メールアドレスが記述された場合、Showdown ではメールアドレス収集ロボットに認識されにくいコードに変換します。HTML Output に切り替えてどのように変換されるか確認してみてください。
- 人間はこれを読めますが、ほとんどの収集ロボットはこれをメールアドレスだとは認識できないはずです。: me@privacy.net
見出し
HTML の "h1" から "h6" でマークアップされる見出しを記述するのに、Markdown 記法では２通りの方法があります。
上位２つの見出し(h1 と h2) は下記のように、文字列の下行にそれぞれ "=", "-" を続けて記述します。
見出し h1
見出し h2
= や - をいくつ書けばいいかは決まっていません。ひとつだけ書いても有効です。でも見やすくするためにはある程度続けて書いたほうがいいでしょう。
また、別のやり方として下記のような記法も有効です。
見出し h1
見出し h2
見出し h3
見出し h4
見出し h5
見出し h6
後ろの閉じる # は必須ではありません。
水平線 hr
ハイフン・アスタリスク・アンダースコアを３個以上続けて行中に記述すると、HTML で "hr" と記述される水平線 (horizontal rule) を挿入できます。
間にスペースがあっても大丈夫。
これらの例は全て同じように出力されます。
リスト ul, ol
単純なリスト
順序なしリストの場合
訳者:kyorecoba注 - 原文では "bullet lists" という表記でしたが、行頭に付加される記号はスタイル指定によっては "bullet" であるはずもなく、意味を汲んで「順序なしリスト」と表記しました。
- マイナス記号に続けてスペースを開けて項目文字列を記述
- プラス記号でも可
- アスタリスクでも可
順序リストの場合
- 数字とピリオドに続けてスペースを挟んで項目を記述
- 次の数字は自動的に決定される
- "7" と記述しても実際の項目番号は "3"
項目内での段落挿入
下記のように書くと、"li" 内の文字列が "p" で括られます。
訳者:kyorecoba注 - 原文では "Double spaced lists" という表記でしたが、別に空白行を必ずしも挟むわけではなく、HTML 的には上のような出力となります。
この文字列は
<p>タグで括られます。ですから見かけ上は空行を挟んだリストになります。
高度なリスト: ネストするリスト
リストの各項目の中にさらにリストをネストさせることができます。
ひとつの項目の下行にスペースを４つ続けて記述すると下層レベルのリストを記述することができます。
ひとつめの項目：
- ４つのスペースを行頭に挿入します。
- ここは８つのスペースを入れてみました。
- もう一度４つのスペースに戻します。
- ４つのスペースを行頭に挿入します。
複数の段落のあるリスト項目：
その場合も、行頭に４つのスペースを挟みます。 ３つでもいいのですが、ややこしいので４つに統一しておくべきでしょう。
このように第一行目でインデントするようにして段落としての体裁を整えます。 実際のところ、このようなことはよくやります。
この段落もまだ上の段落と同じ項目にあり、目で見てもそのように見えます。 最初の２つの段落と同じように、手作業で適当に改行するのも悪くありません。
ブロック引用のあるリスト項目：
空行をひとつ挟んでから やはり４つのスペースでインデントして ">" を行頭に置いてから記述し始めます。
整形済みテキストのあるリスト項目：
空行をひとつ挟んでから ８つのスペースでインデントします。 ４つのスペースはリスト内の記述のためであり、 もう４つは整形済みテキストブロックの開始を 規定するわけです。
ブロック引用 blockquote
単純な blockquote
普通、"blockquote" はインデントされるのが普通ですが、どのような外観になるのかは CSS によります。
こんな引用符はメールでよく使われます。 行毎に引用符をつける必要はありませんが、 つけたほうがきれいに見えます。 まあ好き好きではありますが…。
高度な blockquotes: ネスト構造
他の Markdown 記法による "blockquote" ; > の後ろにスペースを挟んで続けて文字列を記述するだけです。
段落を持つ blockquote:
空行の行頭に ">" を記述するかどうかは任意です。 ">" が記述されているかどうかについては Markdown 記法は関知しません。
でも、空行の行頭であっても ">" を記述した方が 目で見て、同じ "blockquote" 内に段落の境界があることがわかるので そのようにしておくのが望ましいです。
blockquote の中の blockquote:
普通の "blockquote" はインデントされます。
ネストした "blockquote" はより深くインデントされます。
さらに深くインデント。
blockquote の中のリスト :
- "blockquote" の中のリスト
- ">" に続けてスペースを挟み、ハイフンなどのリスト用の識別子を記述します。
- さらに４つのスペースを続けるとリストをネストさせることもできます。
blockquote の中の 整形済みテキスト:
都合５つのスペースを ">" の後に挟んでから記述します。 １つのスペースはblockquote であることを認識させるためであり、 あとの４つで整形済みテキストであることが認識されます。
画像
画像はリンクアンカーの記法に似ていますが、その先頭に感嘆符 (!) が付きます。
.
ブラケットで挟まれた文字列は、alt 属性の文字列となり、画像非表示のブラウザで画像の変わりに表示される文字列です。
音声ブラウザを使う目が不自由な人のために意味のある文字列を記載すべきでしょう。
title 属性の表示も含め、記法そのものはリンクアンカーの要領で記述します。:
This page is .
注意:
現在のところ、Markdown 記法はリンクアンカーの記法で用いられた一番短くて済む記法を画像においてはサポートしていません。下記の記法だと画像は表示されません。
Here's a broken !checkmark.
しかし、下記のように空の一対のブランケットを続けて記述すると、少しだけ冗長にはなりますが、正しく表示させることができます。
This works.
参照名として (valid icon) も alt テキストとして試用できます。
文書中の HTML の扱い
Markdown 記法で扱っていないような HTML を使いたい場合は、そのまま記述すすることができます。:
取り消し線を使ったジョークは このようにできます。
Markdown 記法はインラインで記述された HTML を無効にしない程度には賢いです。
ここの Markdown 記法は すばらしい。
ブロック要素 は少し改変される可能性があります。:
- 前後を空行で挟まれた領域は他の要素とは分けて解釈されてしまいます。
- 一番外側のブロック要素はインデントされません。
- ブロック要素内の Markdown 記法は無視されます。
例えば:
整形済みテキスト pre
整形済みテキスト "pre" も Markdown 記法では使えます。
"code" ブロックとして指定する場合は、４つのスペースによるインデントを加えます。:
printf("goodbye world!"); /* 彼の遺書は C で
書かれている */
これによって <pre> と <code> とが連続したタグでマークアップされます。多くのブラウザでは幅固定フォントで表示されます。最初の４つのスペースは変換後は除去されますが、それ以外はスペースとして認識されます。
この中では Markdown 記法も HTML も使うことができません。そのまま表示されてしまいます。ですから、むしろ簡単に HTML コードを記述することができます。:
<blink>
ここの記述が "code" ブロックでないとしたら
いやでしょう…(笑)
"blink" なんて嫌われていますからね。
</blink>
コード code
バックチックを使うと、インライン要素である "code" のマークアップができます。
<Tab> キーを押した後、$を押します。
(バックチックは日本語キーだとシフトを押しながら、"@" を打鍵すると入力できます。違う場合もありますが…)
インライン要素であっても "code" でマークアップされた文字列は幅固定フォントが使われます。もちろん、Markdown 記法と HTML もまた "code" 内では無効です。:
Markdown 記法の "em" 要素の記述を試みるとこのようになります。: *大*好き！
CSS の代わりに <font> タグは使わないように…。
