おもこん

おもこんは「思いつくままにコンピュターの話し」の省略形です

はてなブログのMarkdown徹底解説

※ 強調についての記事に誤りがありましたので訂正しました(2022/7/19)。

はてなブログの編集モードは4つあり、そのうちのひとつが「Markdownモード」です。 しかし、はてなのヘルプにはMarkdownの書き方についてのまとまった記載がありません。 そこで「はてなブログにおけるMarkdownの書き方」をまとめてみます。

目次

はてなMarkdownとは?

はてなブログでは記事の書き方(記法)を指定することができる。

ここでは、3つ目のMarkdownモードにおける書き方を説明する。

はてなブログ開発ブログ」の2012年9月19日の記事「Markdown記法に対応しました」では、

と書かれている。 この記述から、はてなブログMarkdownでは

が使えると考えられる。 本稿では、この3点を順に説明していきたい。

オリジナルのMarkdown記法

オリジナルのMarkdownは2004年に開発された。 開発の目的は次にように述べられている。

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

マークダウンは、ウェブ・ライターのためのテキストからHTMLへの変換ツールである。 マークダウンは読みやすく書きやすいプレーン・テキスト形式であり、それを構造化された正規のXHTML(またはHTML)に変換する。

HTMLはヘッダやタグのために読みにくく、書きにくい。 それに対して読みやすく、書きやすいマークダウン形式を作り、それをウェブ用のXHTMLやHTMLにすれば、ウェブ・ライターの大きな助けになると考えられたのである。 そして、それが正しかったことは、今日「はてなブログ」をはじめ、数多くのウェブサイトがMarkdownをサポートしていることで証明されている。 Markdownの文法(書き方のルール)は小さく押さえられているので、誰でも容易に習得することができる。

オリジナルのMarkdownウェブサイトは現在でも存在し、その中に文法の詳細な説明がある。

ブロック要素

Markdown記法は大きく2つに分かれ、ひとつがブロック要素、他方がインライン要素(スパン要素)である。 この分類はHTMLにもある。 まず、ブロック要素について述べる。 ブロック要素は、段落、見出し、引用、リスト、コードブロック、水平線である。 基本的にブロック要素とブロック要素の間には空行を入れると考えるべきである。 それが無くても正常にHTMLに変換してくれることも多いが、空行がある方が変換プログラムの文法解析がより確かなものになる。

※ GFMでは、段落の後にリストが続く場合に空行は必要ないことが書かれている。 もちろん、あっても問題ない。 GFMのように空行が無くても正しく解析してくれる実装が現実には多いのかもしれまい。

段落

段落の前後は空行で区切る。 段落の中に空行を入れることはできないから、必然的に段落は連続した行になる。 段落の中の改行は半角空白に変換され各行は前の行の後に詰められる。 もしも、(ほとんど考えられなケースだが)段落の中で改行したい場合は行末に2個以上の半角空白文字を入れる。 これにより、HTMLには<br/>が付け加えられる。 ただ、これは2つの理由から使うべきではない。 第1に行末の2個の空白は目には見えないから、そこでの改行が見逃される可能性がある。 Markdown原稿には無いと思われた改行が、変換後に現れることは好ましいことではない。 第2に段落の途中で改行する必然性がない。 あるとすれば、これを箇条書き用に使うケースだが、箇条書きには後述のリストを用いるべきである。

改行が半角空白に変換される理由は、前の行の最後の文字と次の行の最初の文字がくっついてしまうのを避けるためである。 これは英語の場合に絶対に必要になる。 英語では単語と単語の間、文と文の間は空白で区切らなければならないからである。 日本語では事情が異なるので、改行を半角空白に変換しなければならない理由はない。 むしろ、改行は無くなってほしいのである。 もし、読者が半角空白を嫌うならば、段落中では改行をしないことで問題を解決できる。

段落がHTMLに変換されると、前後にpタグ(<p>)が付けられる。 段落の先頭に半角空白を入れてはいけない(全角空白は構わない)。 段落の中に箇条書き(後述)やその他のブロック要素を入れることはできない。 これは、HTMLのpタグ(段落を表す)がその中にブロック要素を入れ子にできない、というルールがあるためである。

段落と段落の間は改行幅が大きくなるのが通例である。 ただし、これはpタグに対するスタイルシートによる。 はてなブログでは、0.8emのマージンがとられ、見た目で改行幅が1.5倍くらいになっている(筆者の調べによる)。

見出し

見出しの付け方にはSetextスタイルとAtxスタイルがある。 両方の解説をするが、はてなブログではAtxスタイルの###から#####(#が3つから5つ)が推奨される。

Setextスタイルではイコール(=)またはマイナス(-)を見出しの次の行に書く。 これらは<h1>または<h2>に変換される。

見出し 1
========

見出し 2
--------

Atxスタイルでは行頭に#を1から6個連続して書き、その後にスペース、その後にタイトルを書く。 これらはそれぞれ、<h1>から<h6>の見出しになる。

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

はてなブログでは見出しとして<h3>から<h5>を想定している。 それ以外は使わないほうが良い。

参考:はてなブログヘルプ「記事中の見出しから目次を自動的に作成する(目次記法)」の 「Markdownモードで見出しを追加する」

引用

>で始めた行は引用文となる。 >>とすると、引用の中の引用になる。

この記法は、元々電子メールなどで使われていた。 それをMarkdownでも使えるようにしたものである。

引用の中に、見出し、リスト(後述)、コードブロック(後述)を含めることができる。

リスト

リストとはいわゆる箇条書きのことである。

  • 行頭に*または+または-をつけ、その直後に1個から3個の空白文字をつけると順序無しリストになる。順序無しリストはいわゆる箇条書きのことである。
  • 行頭に「1.」,「2.」,「3.」のように数字、ピリオド、1個から3個の空白文字により、順序付きリストになる。順序付きリストは、番号を振った箇条書きである。 このとき、数字は1,2,3のようにせず、1,1,1としてもブラウザ上では1,2,3のような連番のリストになる。
  • リストの間に空行を入れると個々のリストに<p>タグが入り、表示されたリストの間隔が広がる
  • リスト内に段落を設けることができる。 続きの段落の前には空行を入れ、最初の行頭には4個の空白文字を置く。 もし、スペースを入れないと、空行の後は新しい段落とみなされ、リストはその前で終了する。
  • リスト内に引用を含めることができる。 引用の前には空行を入れ、その引用の>の前に4個の空白文字を入れる。 もし、スペースを入れないと、引用は新たなブロックであるとみなされ、リストはその前で終了する。
  • リスト内にコードブロック(後述)を含めることができる。 コードブロックの前には空行を入れ、コードブロックの行頭には8個の空白文字を入れる。
  • リストを終了させるには、空行の後に段落(行頭が空白でない行)を新たに始める。
コードブロック

コードブロックは主にプログラミングコードを表すために用いる。 マークダウンはコードブロックを<pre>と<code>タグで囲んだHTMLに変換する。

  • 行頭にスペース4個またはタブを置くとコードブロックとなる。 コードブロックは書かれた通りにブラウザに表示されるが、その際行頭の4個のスペースまたはタブは取り除かれる。 コードブロック内ではMarkdownの記法は使われず、&は自動的に&amp;エンティティに変換される。 要するに「書かれたままを表示する」のである。
  • コードブロック内のすべての行には上記のインデントが必要である。 コードブロックを終わらせるには、空行の後に新たな段落(行頭が空白でない行)をはじめる。 コードブロックがMarkdown文書の最後に置かれた場合も文書末でコードブロックは終了する。
  • リスト内のコードブロックには行頭のスペースを8個またはタブ2個を置く(リストの項で述べたとおり)。

リストの直後に1行空けてコードブロックを書こうとしても上手く表示されないことには注意が必要。 これは、リストの次に空行があっても、それは<p>入りのリストが続いていると解釈されることと、その先の空行はリスト内の段落と見なされるためである。 そのため、リストの次にコードブロックを書くことを避け、代わりに通常の段落を入れるようにするのが良い。 どうしてもリストの次にコードブロックを入れたい場合は、その間にHTMLのコメントを入れるという手段もある。

この問題は、GFM拡張のひとつであるフェンス・コード・ブロックを使うことで解決できる。 コード・ブロックでは、オリジナルの「行頭4個の空白方式」は、ごく一部の場合を除いて良い方法ではない。 基本的にフェンス・コード・ブロックが推奨される。

※ フェンス・コード・ブロックの書き方を「そのまま」示したいときに、「行頭4個空白のコード・ブロック」が有効である。

水平線

「*」または「-」または「_」を3つ以上並べると水平線になる。

インライン要素(スパン要素)

ブロックの内部で使うMarkdown記法をインライン要素またはスパン要素という。

リンク

リンクにはインラインとリファレンスの2種類がある。 両者ともに、リンクが付いたテキストは角カッコ([と])で囲まれる。

インライン・リンクは[テキスト](URL)の形をしている。 URLの後に"で囲まれた文字列を入れると、タイトルになる。

リンク先は[ここ](http://abc.def-ghi.co.jp)です。
タイトル付きのリンクは[このように](http://abc.def-ghi.co.jp "リンク先")なります。

タイトルは、カーソルをテキスト上に持ってきたときに表示される。

リンク先のURLは同一サーバ内であれば、相対アドレスでも良い。

リファレンス・リンクは、[テキスト][id](idは数字であることが多い)の形で本文中に入れ、それとは別の場所に、[id]:リンク先 タイトル文字列 を書く。 本文とリンク先を分けて書けるので、脚注のような形でリンクを表現できる。

本文中に[リンク先][1]を書く。
リンク先は別の段落。

[1]: http://abc.def-ghi.co.jp "リンク先"

ブラウザには本文のみが表示され、idとURLを書いた行は表示されない。

この方法は、同一のリンク先が本文中に複数あるとき、とくに有効である。 なぜなら、リンク先を1ヶ所に記述すればすむので、タイプミスを防ぐことができ、タイプ量を減らすことができるからである。

リファレンス・リンク中のidには数字の他、英字、記号、空白なども使える。 英語の大文字小文字は区別されない。 したがって、「A」と「a」は同じidを表す。 idを角カッコのみにすると、テキストがidとみなされる。

[Hatena][]

[Hatena]: https://hatenablog.com/ "はてなブログ"

リファレンス・リンクを用いると、Markdownの本文がよりブラウザ表示に近い形で表され可読性が増す、という利点がある。

以上の基本的なリンクを表す記法の他に、短縮形として<URL>の形が可能である。

はてなブログのアドレスは<https://hatenablog.com>です。
強調

「*」、「_」で囲まれた文字列は強調(<em>)される。 「**」、「__」で囲まれた文字は強く強調(<strong>)される。

この*テキスト*は強調されます。
この_テキスト_も強調されます。
この**テキスト**はより強調されます。
この__テキスト__はより強調されます。

一般的には、emタグがイタリック体(斜体)になり、strongタグがボールド(太字)になる。 しかし、「はてなブログ」の「Novel」デザインでは、emタグがノーマル・スタイルで表示され、強調が効かない。 そのような場合、スタイルシートをカスタマイズすることにより、emタグを斜体にできる。 「設定」から「詳細設定」を選び、「<head>要素にメタデータを追加」の入力枠に<style>em{font-style:italic;}</style>と書き、「変更する」ボタンをクリックする。 これでemタグが斜体になって表示されるようになる。 このスタイルシートの効果はブログ内のすべての記事に及ぶ。

もともと、HTMLタグは見栄えを定義するものではない。 見栄えを定義するのはCSSである。 したがって、「斜体で表現したい」場合は、その部分にCSSを使うのが正しい方法である。

これは<span style="font-style:italic;">斜体</span>です

と書けば

これは斜体です

と表示される。

後ほどエスケープのところで述べることだが、アスタリスク(*)やアンダースコア(_)自体を表示したいときは、バックスラッシュをつけてエスケープする。

コード

バックティック(`)で囲まれた文字列はコードと見なされ、<code>タグで囲まれるように変換される。 コード中にバックティック自身を入れたいときは、コードを2個のバックティックで囲む。

`This is a code.`
``This is a backtick quotes (`).``

コードには空白文字を入れることができる。 バックティック1文字だけのコードを作るには空白文字が必要になる。 (そうでないと、バックティックが5個連続することになる)。

コードではMarkdownの記法は意味を失い、アンパサンド(&)は&amp;エンティティに変換される。 したがって、「書かれた通りに表示」される。

画像

画像はリンクと似ているが、角カッコの前にエクスクラメーション・マークを付ける。

![代替テキスト](画像ファイルへのリンク) "タイトル"
![代替テキスト][id]

[id]: 画像ファイルへのリンク "タイトル"

タイトルは省略できる。 代替テキストは、画像が表示できないときにその代わりに表示される文字列である。

Markdown編集モードの右側ペインの「+写真を投稿」ボタンをクリックしてアップロードした画像に対しては、この方法ではなく、別の方法を用いる。 「fotolife記法」を参照してほしい。

エスケープ

*や_などの文字自身を書きたい時は、\でエスケープする。 エスケープの対象となるキャラクタは

\, `, *, _, {, }, (, ), [, ], #, +, -, ., !

である。

HTMLにおいて、<と&は特別な文字で、この2つは別のやり方でエスケープが必要である。 (注意:Markdownの中ではなくHTMLの中での話しである)。

  • <はHTMLタグを開始する文字である。 <をその文字自身として表したいときは&lt;と書く。
  • &はHTMLエンティティ(HTMLの予約済み文字(<や>など)や見えない文字を表示するための記号)の開始文字である。 &をその文字自身として表したいときは&amp;と書く。

特に&amp;エンティティはリンク先アドレスでも使うので、注意が必要である。

この2つの文字について、Markdown記法が適用される部分では自動的にエンティティに変換される。

  • HTMLタグでない<は自動的にエンティティ&lt;に変換される。
  • HTMLエンティティでない&は自動的に&amp;に変換され、エンティティ&amp;や&copy;は変換されずに&amp;や&copy;となる(HTML内でもエンティティ)。 これにより、Markdown内で&copy;と書いた部分はブラウザでは©と表示される。

以上から、通常はマークダウン中で<と&はそのまま書いて問題ない。 気をつけなければいけないのは、<と>がペアになり、ちょうどHTMLタグのようになる場合で、そのときは&lt;と書かなければならない。

HTMLの埋め込み

Markdownの文書中にHTMLタグを書くことができる。 ブロック・レベルのHTMLタグには次のような制限がある。

  • ブロック・レベルのHTMLタグ(<div>, <table>, <pre>, <p>など)は空行でその外側のテキストと切り離されなければならない
  • 開始タグと終了タグはタブや空白でインデント(字下げ)してはならない
  • HTMLブロックの中ではMarkdown記法を使うことはできない

これに対して、インライン・レベルのタグ(<span>, <cite>, <del>など)は制限なくどこにでも書くことができる。 注意すべきは、インライン・レベルのタグに囲まれた部分でもMarkdownの記法が有効であることである。

HTMLを使うと、取り消し線、アンダーラインなどを表現できる。

これは<s>取り消し線</s>で、これは<u>アンダーライン</u>です。

これは次のように表示される。

これは取り消し線で、これはアンダーラインです。

CSSを使って取り消し線やアンダーラインを表現することもできる。 それにはtext-decorationプロパティをそれぞれline-throughまたはunderlineに設定すれば良い。

これは<span style="text-decoration:line-through;">取り消し線</span>で、これは<span style="text-decoration:underline;">アンダーライン</span>です。

これは取り消し線で、これはアンダーラインです。

同様にして、CSSでテキストの色を変えることなどができる。

はてなブログで使えるGFM拡張

GFMはGithub Flavored Markdownの頭文字をとったもので、Githubで用いられているMarkdownである。 はてなブログではその一部が使用可能であるとされているが、どの機能がサポートされているのかは、はっきりしていない。 ここでは、私がはてなブログで使えたものを記す。 読者がこの他に使える機能をご存知であればぜひコメントで教えていただきたい。

フェンスコード・ブロック

コードブロックはオリジナルでは行頭の4個の空白で表されたが、これは可読性の点であまり良いとは言えない。 それに対して、フェンスコード・ブロックは行頭の空白が要らないのでより可読性に優れていて、推奨できるものである。 コードフェンスブロックは3個のバックティック(`)からなる行で前後を囲んだブロックである。

```
int main (int argc, char **argv) {
  printf("Hello world.\n);
}
```

バックティックの後にプログラミング言語名を追加するとブラウザ表示のときにシンタックス・ハイライトをしてくれる。

```ruby
10.times do |n|
  print "%d\n", n
end
```
10.times do |n|
  print "%d\n", n
end

Githubではティルダ(~)でもフェンスコード・ブロックを作れるが、はてなブログでは基本的にバックティックのみである。

シンタックス・ハイライトは、はてなブログヘルプのソースコードを色付けして表示する(シンタックスハイライト)に説明がある。 また、同ページにシンタックス・ハイライトできるファイルタイプの一覧がある。

バーティカル・バー(|)とハイフン(-)を用いて表を作ることができる。

|タイトルA|タイトルB|備考|
|---------|---------|----|
|パソコン |アダプタ |2   |
|プロジェクタ|HDMIコード|1|

これがブラウザ上では次のように表示される。

タイトルA タイトルB 備考
パソコン アダプタ 2
プロジェクタ HDMIコード 1

タイトル行と本体の間のハイフンにコロン(:)をつけて、各項に左寄せ、右寄せ、センタリングを指定できる。

  • |:---| 左寄せ
  • |---:| 右寄せ
  • |:--:| センタリング
|タイトルA|タイトルB|備考|
|:---------|--------:|:----:|
|パソコン |アダプタ |2   |
|プロジェクタ|HDMIコード|1|
タイトルA タイトルB 備考
パソコン アダプタ 2
プロジェクタ HDMIコード 1

リストのネスト

GFMでは、ネスト(入れ子)になったリストを作ることができる。 「はてなブログ」のMarkdownでもネストがサポートされている。

Markdownの編集画面

- 1段階目の項目(1)
  - 2段階目の項目(2)
    - 3段階目の項目(3)
    - 3段階目の項目(4)
  - 2段階目の項目(5)
- 1段階目の項目(6)
  - 2段階目の項目(7)
  - 2段階目の項目(8)
- 1段階目の項目(9)

プレビュー画面

  • 1段階目の項目(1)
    • 2段階目の項目(2)
      • 3段階目の項目(3)
      • 3段階目の項目(4)
    • 2段階目の項目(5)
  • 1段階目の項目(6)
    • 2段階目の項目(7)
    • 2段階目の項目(8)
  • 1段階目の項目(9)

2段階目は行頭に2個の半角空白(以下「半角」を省略)、3段階目は2段階目より空白を2個多くとる。 「順序付きリスト」でもネストができるが、一段深いサブ・リストは空白を(2個ではなく)3個多くしなければならない。 行頭の空白の数は、リストを作る記号「-」や「1.」などが、前の行の項目本体の位置までインデントするのに必要な数に等しい。 「順序なしリスト」では「-」「空白」の2文字の次から項目本体が始まるので、2個の空白が必要なのである。 「順序付きリスト」では「1」「.」「空白」の3文字の次から項目本体が始まるので、3個の空白が必要なのである。

ネストされたリストを使う機会は少ないが、ときには便利なこともある。

はてなブログ独自の拡張

冒頭に述べたように、Markdownでは「自動リンク記法」が使える。 これについては、はてなのヘルプに説明がある。

自動リンク記法

  • http記法。URLを書くと自動的にそのURLにリンクを貼る。 [http//〜〜:タイトル]という書き方もできる。 後者の書き方では、ブログカードでリンクを表示する「埋め込み」などができる(後述)。
  • google記法[google:〜〜]と書く。ブラウザで表示されたものをクリックすると「〜〜」をGoogleで検索した結果が表示される。
  • wikipedia記法[wikipedia:〜〜]と書く。同様に「〜〜」のwikipediaのページにジャンプする。
  • 自動リンク停止記法。[ ]〜〜[ ]と書くと、リンクされない。

はてな自動リンク

「埋め込み」「タイトル」「URL」

http記法のリンクでは「埋め込み」「タイトル」「URL」ができる。 これらは、リンクボタンを使うと簡単に作ることができる。

  • 「リンクボタン」をクリックする
  • 現れたダイアログにリンク先URLを記入し、「プレビュー」ボタンをクリックする
  • 「埋め込み」「タイトル」「URL」のいずれかを選択し、「選択した形式でリンクを挿入」をクリックする。

以下にそれぞれの「はてな記法」とプレビューを示す。 リンク先はこの記事である。

編集画面

「埋め込み」(サイテーションあり)

[https://toshiocp.com/entry/2022/07/09/235226:embed:cite]

「埋め込み」(サイテーションなし)

[https://toshiocp.com/entry/2022/07/09/235226:embed]

「タイトル」

[https://toshiocp.com/entry/2022/07/09/235226:title]

「URL」

[https://toshiocp.com/entry/2022/07/09/235226:title]

「埋め込み」(サイテーションあり)

toshiocp.com

「埋め込み」(サイテーションなし)

「タイトル」

はてなブログのMarkdown徹底解説 - おもこん

「URL」

はてなブログのMarkdown徹底解説 - おもこん

見出しへのリンク

はてなブログ」のMarkdown記法では、見出しから変換されたHTMLタグに「#見出し名」のidを付けている。 例えば、

#### はてな記法

という見出しは

<h4 id="#はてな記法">はてな記法</h4>

というHTMLタグになる。 idに対してはリンクを貼ることができるので、

[これ](#はてな記法)をクリックすると、「はてな記法」という見出しへ飛びます。

このような書き方で、見出しへのリンクを貼ることができる。

目次記法

目次記法は、見出しから自動的に目次を作る記法である。 はてなブログのヘルプの記事中の見出しから目次を自動的に作成する(目次記法)に説明がある。 この機能は、「見たままモード」「はてな記法モード」「Markdownモード」で使える。

[:contents]

目次記法は自動的に目次となって表示される。 目次になるのは、本文中の見出し(3個から5個の連続する#のあとに空白があり、その後に見出しの文字列が続くもの)である。 #の数が3から5になっているのは、はてなブログがそれらのみを見出しとして想定しているからである。

  • ###は大見出し(<h3>)
  • ####は中見出し(<h4>)
  • #####は小見出し(<h5>)

なお、本来のマークダウンでは1個から6個が<h1>から<h6>に対応する。

フォトライフ記法

フォトライフ記法が「はてな記法モード」と「Markdown記法」モードで使える。 はてなブログヘルプのはてなフォトライフの写真を貼り付ける(fotolife記法)に説明がある。

フォトライフ記法は、投稿した写真を記事に貼り付けるときに用いられる。 [f:id:はてなID:画像番号:オプション]の形で記述する。

[f:id:hatenablog:20170217161727j:plain]
[f:id:hatenablog:20170217161727j:plain:title=パンダ:alt=アドベンチャーワールドで見たパンダ]

画像の上にマウスを重ねると、title属性の値がツールチップで表示される。 画像を表示できないときに、alt属性の値が代替テキストとして使用される。

オプションをコロンのあとに付け加えられる。 alt、title以外に表示幅、高さを指定できる。

  • wDD Dは数字。表示幅
  • hDD Dは数字。高さ
  • alt= 代替テキスト
  • title= 画像のtitle属性

tex記法

[tex:〜〜]で、「〜〜」のところにTeXの数式表現を記すことができる。 数式を表現するのにMathJaxが使われている。

数式の書き方は、LaTeXの書籍やウェブサイトを参照してほしい。

ここで、注意しなければならないのは、〜〜のところにもMarkdown記法が適用されるので、アンダースコア(_)などはエスケープしなければならないことだ。 そのため、意外に使いにくい。

また、tex記法はインライン要素なので、別行立て数式を書く場合はブロックの中に入れなければならないということだ。 例えば、運動方程式を別行立て数式で表示するには次のようにする。

<div style="text-align:center;">
[tex: \displaystyle
F = ma
]
</div>

これは次のように表示される。

 \displaystyle
F = ma

ブロック要素のHTMLの中ではMarkdown記法は効果を発揮しない。 したがって、tex記法内で_^エスケープする必要がない。 (^は脚注を表すGFM拡張)。 上記ではdivタグを使ったが、preタブでも良い。

別行立て数式はこのようにdivタグまたはpreタグで囲うのが良い方法である。

サンプルエントリー

はてなブログヘルプにMarkdownのサンプルがある。 サンプルエントリーを参照してほしい。 Markdownの記述の参考になるはずである。