gihyo.jp編集部におけるMarkdown記法

本稿では、gihyo.jp編集部で利用しているMarkdownファイルの記述方法を主に解説します。

注意：gihyo.jp編集部内でのみ採用しているMarkdownの書き方をまとめた文書を、記事の体裁を取って公開したものです。なお、記事公開後に記述方法を追加・変更する可能性もあります。

Markdownとは？

はじめに、筆者の把握している範囲でMarkdownについて概説しておきます。

近年は一般向けのウェブサービスやテキストエディタでも利用されてきているMarkdown。端的に言えば、テキストファイル上で文書を書くための構文です。文書の読みやすさに焦点を当てており、Markdown形式のテキストファイル（＝Markdownファイル）をそのまま見れば文書とその構造が理解できるように、Markdown特有の編集記号や字下げを用いて表現します。また、MarkdownファイルをHTMLファイルに簡単に変換することも意図して作られています。そのためMarkdownの仕様に付随して、変換のためのプログラムが提供されています。なお、Markdown形式のファイルの拡張子としてmd（またはmarkdown）が主に使われます[1]。

Markdownの歴史を少し振り返っておきましょう。もともとのMarkdownはJohn Gruberさんが2004年に作りました。その後Markdownの使い勝手が良かったことから、彼の手を離れて独自に拡張されていきます。というのも、もともとのMarkdownは作者自身の目的に合うように基本的な構文のみが定義されていたことと、そして簡単に構文を拡張しやすかったからでしょう。初期に拡張されたMarkdownの例としてはPHP Markdown Extra、MultiMarkdown、Pandoc's Markdown、R Markdownあたりが有名でしょうか。そして2014年、正確にHTMLに変換させるために、Markdownを利用しているグループがMarkdownの細部を再定義してCommonMarkを作りました。またIETFでも、Markdownに関する参考情報をRFC 7763で取りまとめています。現在ではウェブサービスやフレームワークごとにCommonMarkに準拠していたり、CommonMarkをより拡張していることが多い印象です。たとえばGitHub Flavored MarkdownやGitLab Flavored Markdownなどは有名でしょう。各種エディタでもMarkdownを書きやすくするために、標準でCommonMarkに対応していたり、Markdownを書くためのプラグインなどが有志により提供されています。

近年は一般向けの記事執筆やメモを取ったり文章を記述したりするウェブサービスでもMarkdownが利用されています。国内ではQiitaやZenn、Noteなどが有名でしょうか。海外のウェブサービスだと最近はNotionやObsidianがよく挙げられている印象です。また先日GoogleドキュメントでもMarkdownの基本構文を用いて入力できるようになったことも記憶に新しいところです（標準でMarkdownとして出力できるようになったわけではありません⁠）⁠。しかしながら、各ウェブサービスにおいて同一表現の拡張構文の書き方が異なっていたり、とあるサービスでの拡張構文が別のサービスでは対応していなかたったりすることがあります。

Markdownの構文を簡単に拡張できることは利用者を増やした要因の一つでしょう。しかしウェブサービスごとに拡張した構文が異なるのは、多少なりとも気を使うことになります。CommonMarkのフォーラムでは拡張された構文の統一について一応議論されていますが、進展がある気配はないようにみえます。もともとのMarkdownでは、複雑な記述はHTMLを使って書くことを許容しています。しかしMarkdownの基本方針として、HTMLタグを書かずに読みやすさ・書きやすさを重視していることも事実です。そういうわけで、仕様ごとの拡張構文が減ることはないように思います。時間をかけて同じ拡張構文に収斂されていくでしょうが、このあたりも含めてMarkdownの文化と言えるのかもしれません。

なお、gihyo.jp編集部で使っているMarkdownの構文も独自に拡張しています。画像などのキャプションや意味付けしたブロックなどがあり、本文の文字列（語彙）を利用して拡張しているのが特徴的かもしれません。

テキストの記述

それでは、Markdownの書き方を説明していきます。

Markdownファイルでは構文を規定するために、特定の記号文字\`*_{}[]()#+-.!を編集記号として使います。ただし構文を規定する編集記号の使い方でなければ、その編集記号自体をそのまま書くことができます。なお編集記号自体を強制的に書きたい場合には、編集記号としての役割を解除するための制御記号\をその直前に書くか、またはコードとして表現します。

重要を示す編集記号の`**`を本文として書くにはコード化するか、\\を使って\*\*のようにエスケープします。

ノート：Markdownファイルはテキストファイルですので、特定の文字コードと改行コードが使われます。基本的には、文字コードをUTF-8（BOMなし⁠）⁠、改行コードをLFの組み合わせにしてください。

HTMLの記述

MarkdownファイルにはHTMLを直接書くことができます。HTMLタグにはいわゆる、段落内で使われるタグ（インライン要素）と段落が並ぶ方向に置かれるタグ（ブロック要素）があります。このインライン要素とブロック要素のタグでは少し扱いが異なります。

インライン要素は普通に記述して使えます。しかし、ブロック要素を記述する際は、その上下に空白行が必要です。なお、本文としてHTML自体を記述したい場合にはコードの編集記号`で括る必要があります。

注意したい点として、もともとのMarkdownでは、ブロック要素のHTML内ではMarkdownの編集記号が効かず、単に文字として解釈されることに注意が必要です。しかしCommonmarkでは、たとえばdiv要素の開始タグの直後に空白行があり、かつ終了タグの直前に空白行がある場合、その内部がMarkdownとして解釈されます（gihyo.jpでもこの動作です⁠）⁠。

段落。段落。段落。段落。段落。段落。段落。

<div id="box1">
**この行の*は変換されずにそのまま表示されます。**
</div>

段落。段落。段落。段落。段落。段落。段落。

<div id="box2">

**Commonmarkの場合、この行は両端の*が変換されて重要な文として表示されます。**

</div>

段落。段落。段落。段落。段落。段落。段落。

段落

Markdown特有の編集記号によって意味付けがされていない、文章行のまとまりは基本的に段落になります。改段するためには段落間に少なくとも1行、空白行を挿入します。

1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。1つ目の段落。

2つ目の段落。2つ目の段落。2つ目の段落。2つ目の段落。2つ目の段落。
2つ目の段落。2つ目の段落。2つ目の段落。2つ目の段落。2つ目の段落。


3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。3つ目の段落。

通常のMarkdownでは、段落内で単純に改行した場合、HTML出力したときに改行のまま処理されるため、HTML上では単に半角スペースとして表示されます。英語の文章では、英語自体が単語間にスペースを入れる言語のため、特に問題がおきることはありませんが、日本語の文章では問題となるため注意が必要です。

設定や仕様によっては段落内で空行を開けずに改行した場合に、この改行を取り除くものもあります。これによりHTML上で日本語文章で余計な半角スペースが表示されなくなるため、上記の注意は必要なくなります。しかし英文での単純改行の処理で困ることになるため、一長一短です。

gihyo.jpでは、改行場所の行末文字または改行後の行頭文字の両方がASCII文字（いわゆる英数字などの半角記号）ではないとき、改行を取り除いて表示します。

A Paragraph.
The line break just before this is displayed as a single-byte space in HTML.

日本語であれば改行しても問題ありません。
この直前の改行（HTMLでは半角スペースとして表示）は削除されます。

ノート：筆者としては、ー文ごとに改行するのはお勧めしません。一目で段落の分量が把握しにくいからです。

段落内の改行

段落内で強制的に改行したい場合があります。その場合には強制改行したい場所で半角スペースを2つ入れて改行し、その次の行に続きを書きます。CommonMarkでは、半角スペース2つの代わりに\を書くことでも改行できます。Markdownファイル内では、どちらかに統一しましょう。または を直接書いてしまう方法もあります。

段落。段落。段落。段落。段落。段落。  
段落。段落。段落。段落。段落。段落。

段落。段落。段落。段落。段落。段落。\
段落。段落。段落。段落。段落。段落。

見出しなしの話題の転換

見出しをつけずに話題を変えたい場合があります。その場合には、段落間で次のように*または-を書き、その文字を3つ以上含む行を作ります（一つの種類のみを使います⁠）⁠。なお、記号の間に半角スペースが入っていても構いません。これにより話題の転換を示す区切り（HTMLのhr要素）を埋め込めます。CommonMarkでは_の記号も使えます。Markdownファイル内における話題転換の記号は、どれか一つの記号のみを使うと良いでしょう。

段落。段落。段落。段落。段落。段落。

***

段落。段落。段落。段落。段落。段落。

* * * * *

段落。段落。段落。段落。段落。段落。

ノート：後述の意味付けしたブロックでも見出しなし話題転換の記号を利用するため、使い分けと使用頻度の兼ね合いから、見出しなし話題転換の記号として*を使うことを筆者としてはお勧めします。

文書作成中にはコメントがつきものです。もちろん文書ファイルに付随する環境（GitHubなど）でコメントを記述しやすい場合には、それを利用するのも良い手段です。ただ場合によっては、Markdownファイル上にコメントを記述したいときがあります。しかしMarkdownとしてはコメントを指定する記号がありません。

HTMLコメント

そこで考えられるのがHTMLのコメントの利用です。つまりで囲んだ部分をコメントにできます。ただしHTMLに変換した際には、そのままHTMLコメントとして出力されてしまうのが一般的ですので注意してください。

段落。段落。段落。段落。段落。段落。

<!--コメント。
コメント。
コメント。-->

段落。段落。段落。<!--コメント-->段落。段落。段落。

スターコメント〘拡張構文〙

さらにgihyo.jpでは、コメントして★囲みをコメントとして扱います[2]。これはHTMLに変換した後は基本的に表示しません。また、段落の行頭を★から始めた場合、その段落はコメント段落として扱います。

段落。段落。段落。★コメント★段落。段落。

★コメント段落。コメント段落。コメント段落。コメント段落。
コメント段落。コメント段落。コメント段落。コメント段落。

文章中の編集記号

この節では、段落や箇条書きなど、文章中の編集記号をまとめます。

リンク

MarkdownではHTMLと同様にリンクを設定でき、その書き方はいくつかあります。

リンクを設定したい文章中の語句と隣り合わせにURLを書く方法がその一つです。次のように[リンクしたい文字列](URL)として書きます。なお、HTMLのtitle属性を埋め込むことも可能です。その場合にはURLの後に、半角スペースを入力して"で囲んで指定しますが、一般的にtitle属性を指定することはないでしょう（"の代わりに'で囲ったり、()を使うこともできます⁠）⁠。

出版社は[技術評論社](https://www.gihyo.co.jp/)です。[電子書籍](https://gihyo.jp/dp "Gihyo Digital Publishing")も販売しています。

URLを本文から分離して次のようにも書けます。こちらの記述のほうが本文が読みやすくなりやすいです。例の中のgihyoや電子書籍サイトの文字列は識別子であり、自由に設定できます。ただし英字の大文字と小文字は区別しません。

出版社は[技術評論社][gihyo]です。[電子書籍][電子書籍サイト]も販売しています。

[gihyo]: https://www.gihyo.co.jp/
[電子書籍サイト]: https://gihyo.jp/dp "Gihyo Digital Publishing"

段落。段落。段落。段落。段落。段落。段落。

この記述は識別子の指定を略すことができ、次のように表示上の文字列をそのまま識別子にして書けます。異なる文字列に対して一つURLを設定する場合以外では、この略した書き方がお勧めです。

[技術評論社][]は出版社です。[電子書籍][]も販売しています。

[技術評論社]: https://www.gihyo.co.jp/
[電子書籍]: https://gihyo.jp/dp "Gihyo Digital Publishing"

段落。段落。段落。段落。段落。段落。段落。

本文にURL文字列を直接掲載し、かつリンクに設定したい場合には、URLを<と>で囲います。

技術評論社のURLは<https://www.gihyo.co.jp/>です。

なお、URLの文字列に対して<と>で囲わずとも自動的にリンクにできる仕様があります（gihyo.jpではこの動作にはなりません⁠）⁠。

文脈的に強調したい文字列

文章中で*で囲むことで文脈的に強調したい語句を指定できます。強調は後述の重要を意味するわけではありません。強調されている文節・語句が他の箇所よりもアクセントの重みが強いことを意味します。紙書籍では圏点（英語の書籍だと斜体）で表現されることが多いでしょう。gihyo.jpでも基本的に圏点として表示します。

技術評論社は*ITに関連する書籍*を中心に、幅広いジャンルの書籍を刊行している出版社です。

_で単語を囲んでも強調になるのですが、_を使う場合はその外側に半角スペース（または行頭/行末）が必要です。単語の区切りとしてスペースが使われていない日本語の文章中では使いにくいでしょう。

ノート：*で強調する場合でも、外側に半角スペースがなく、かつ強調したい文字列の最初または最後が全角記号や句読点があるときは、Commonmarkでは強調処理がされません。しかしこれはわかりにくいため、gihyo.jpではこの場合でも強調処理されるようにしています。

内容として重要な文字列

文章中で**で囲むことで内容として重要な文字列を指定できます。より具体的には、読者に主張したい文字列として考えてください。紙書籍では（特色の）太字で表現されることが多いでしょう。gihyo.jpでは太字で表示します。

**技術評論社はIT系書籍を主に刊行している出版社**です。

__で囲んでも重要な文字列になるのですが、__を使う場合はその外側に半角スペース（または行頭/行末）が必要です。単語の区切りとしてスペースが使われていない日本語の文章では使いにくいでしょう。

ノート：**で強調する場合でも、外側に半角スペースがなく、かつ強調したい文字列の最初または最後が全角記号や句読点があるときは、Commonmarkでは強調処理がされません。しかしこれはわかりにくいため、gihyo.jpではこの場合でも強調処理されるようにしています。

本文における図表の番号の太字処理〘拡張構文〙

gihyo.jpでは本文における図番号や表番号を太字で表示する場合があります。図や表と数字列が続く文字列を**で囲むことで、その処理を行います。特に必要なければ太字にしなくて構いません。記事内で統一してください。

**図1**では具体的な位置付けを表しています。**表1**では月間の数値を出しています。

ノート：HTMLとしては図1のように変換します。

文章中のコード⁠・端末（ターミナル）文字列

段落内のコードは`hoge`と、バッククォートで囲って書きます。なおコード中に`が出てくる場合には、より大きな数のバッククォートで囲みます。もしコードの最初や最後がバッククォートの場合には半角スペースを入れて編集記号と離すようにします。

`hoge`だったり、``hoge`fuga``だったり。`` `hoge` ``のように書きます。

もちろん段落中のコードを明示的に示さずに、通常の本文扱いで記述しても構いません。ただし、コード内に編集記号の文字があることも考えられ、その場合にはエスケープしなければならないことを考えると、コードはバッククォートで囲う方向で統一したほうが良いでしょう。特にプログラミング関係の記事であればコードとして記述するのが無難です。

また、段落中のターミナル（端末）やパスの文字列は現在、コードと同じように`で囲んで記述して構いません。HTMLとしては<code>タグが使われてしまいますが、これを現在許容しています[3]。

カレントディレクトリを表示するには`pwd`と入力します。すると`/home/user`と返ってきます。

キーボード文字〘HTML利用〙

gihyo.jpでは、キーボード文字をデザイン処理を行いたい場合には普通にHTMLのkbd要素を使うことにします[4]。デザイン処理をしなくても構わない場合にはkbd要素を利用する必要はありません。現在それ以外でkbd要素は利用しないようにしています。

<kbd>Enter</kbd>キーを押してください。

ルビ〘拡張構文〙

Markdownの基本構文にはルビを指定する方法がありません。いくつか拡張構文が見かけます。もちろんHTMLでルビを指定しても構いません。

ノート：HTMLにおけるルビの種類にはモノルビ、グループルビ、熟語ルビ、インラインルビがあります。gihyo.jpではグループルビのみを使っています。

HTMLルビ

HTMLを使う場合、ルビは次のように書けます。

<p>MSIMEでは<ruby>超電磁砲<rp>《</rp><rt>レールガン</rt><rp>》</rp></ruby>を変換できます。</p>

RUBY二重山括弧形式

gihyo.jpでは、漢字または半角英数文字列に対するルビを示す記号として、二重山括弧（《》）を使います。これにより、その文字列に対してルビが付きます。なお、ルビをつける対象語句の範囲を明示的に指定するには<ruby>タグで範囲を指定します。拡張構文に対応していない環境を考慮すると都合が良いため、この形式を採用しています。

MSIMEでは超電磁砲《レールガン》を変換できます。

高出力<ruby>超電磁砲《レールガン》</ruby>を配備しています。

ノート：国立国会図書館の学術文献の視覚障害者等用テキストデータのルビが《》を使っています。

ノート：ルビの拡張構文はいくつかあります。参考までに記載しておきます。

青空文庫形式

青空文庫形式のルビは、gihyo.jpの方法と基本的に同じです。ただし、ルビをつける文字列の範囲を明示的に指定する場合はその先頭に｜を書きます。

高出力｜超電磁砲《レールガン》

DenDenMarkdown形式

電子書籍のマークアップとして使われることがあるDenDenMarkdownでは{ルビをつける文字列|ルビ}と書くことで、ルビを指定します。

{超電磁砲|レールガン}

添え字（上付き文字⁠、下付き文字）

添え字はMarkdownの基本構文にはありませんが、拡張構文をもっている仕様も多いです。またHTMLとして記述したり、数式として扱ったり、文字として直接書いたりする方法があります。

HTMLの添え字

HTMLでは、上付き文字としたい文字はタグで、下付き文字としたい文字はタグで囲みます。

上付き文字はx<sup>1</sup>で表現し、下付き文字はx<sub>1</sub>と記述します。

Markdownの添え字〘拡張構文〙

Markdownの拡張構文として添え字がの構文がある場合、次のように定義されていることが多いです。gihyo.jpでもこの記法を利用できます。

上付き文字はx^1^で表現し、下付き文字はx~1~と記述します。

数式内の添え字

他の方法として、後述の数式表現（ $x^1$ や $x_1$ など）を使う方法もあります。数式であればこの方法は一つの手段です。

Unicodeの添え字

Unicodeに添え字（¹や₁など）があるので、直接書くことができます。ただし添え字の大きさをCSSで調整したい場合に不向きです。また、ほとんどがJIS2004の範囲外なので注意が必要かもしれません。

脚注〘拡張構文〙

脚注はもともとのMarkdownでは定義されていません。しかし脚注の拡張構文が広く使われており、gihyo.jpでも対応しています。

脚注は、文章内の脚注指定とそれに対応する脚注で構成されます。本文中の脚注指定は各原稿ファイル上で[^文字列]とし、脚注は段落外の行、行頭に[^文字列]:を書いて、そのあとに（半角スペースを入れて）脚注文を書きます。

販売している電子書籍のファイルとしてPDF[^pdf]とEPUB[^epub]があります。

[^pdf]: 紙書籍のレイアウトを維持しています。Adobe Readerなどを使って読めます。
[^epub]: 紙のレイアウトとは異なります。Thorium Readerなどを使って読めます。

そのため、自分の環境に合わせて利用できます。

脚注指定の文字列は、HTMLに変換したとき、ファイルの先頭から1、2、3、……という形で表示されます。仕様によっては上付き文字になったり、[1]と表示されたりします。

また、Markdownで広く使われている脚注構文では、脚注をどこで書いてもHTMLに変換したとき末尾に一覧されることが多いです。しかし、gihyo.jpでは脚注入れた箇所に表示します。そのため、脚注を指定した段落直後に脚注を書くようにするのがお勧めです。

ノート：本文中にインラインの形で脚注（PDF^[紙書籍のレイアウトを維持しています]とは…）を書ける仕様もありますが、gihyo.jpでは対応していません。

記事タイトル⁠・見出し

記事タイトル・見出しは、そのレベルに応じて、行頭に1つから6つの#をつけて表現します（ATX Headingsと言います⁠）⁠。その後半角スペースを入れた後に、タイトルや見出し文字列を書きます。その際、見出し行の前後で空白行を設けると読みやすくなるでしょう。

# 見出しレベル1 ★記事タイトル。gihyo.jpではメタ情報側に記述しても構いません★

## 見出しレベル2 ★節見出し。gihyo.jpでは目次に表示されます★

### 見出しレベル3 ★項見出し。gihyo.jpでは目次に表示されます★

#### 見出しレベル4 ★目見出し★

##### 見出しレベル5 ★細目見出し★

###### 見出しレベル6 ★さらに小さい見出し。gihyo.jpでは引用やコラム以外では非推奨です★

記事タイトルにサブタイトルを付けたい場合があります。gihyo.jpでは見出しの末尾に半角スペースを1つ入れてさらに〜（または～）を入れた上で書いてください。その後ろの部分をサブタイトルとして扱います。

# 記事タイトル 〜サブタイトル

なお、見出しレベルは飛ばさないように記述します。たとえば、レベル2の後の見出しがレベル4にならないようにしてください。またgihyo.jpでは、通常本文においてレベル6の見出しは使用を推奨していません。記述リストの利用や構成を再検討してください。

ノート：Markdownでは見出しレベル1と見出しレベル2を次のように記述することもできます（Setext headingsと言われる記法です⁠）⁠。具体的には、見出し文字列の直後の行に、レベル1では=のみの行を、レベル2では-のみの行を書きます。

見出しレベル1
========================

段落。段落。段落。段落。段落。

見出しレベル2
------------------------

段落。段落。段落。段落。段落。

箇条書き

箇条書きには一般的に、順序付きのない箇条書き（通常の箇条書き）と、順序付きのある箇条書きがあります。

順序付きのない箇条書き

通常の箇条書きは、行頭に-、*、+のいずれかを書き、半角スペースを入れた後に箇条書き項目を書きます。段落との間には、上下に空白行を1行入れるようにします。なお、ファイル内では記号の使い方を統一してください。

段落。段落。段落。段落。段落。段落。段落。段落。

- 順序付けのない箇条書き
- 順序付けのない箇条書き
- 順序付けのない箇条書き

段落。段落。段落。段落。段落。段落。段落。段落。

箇条書きの入れ子は、次のように、箇条書きの編集記号の前に行頭に半角スペースを4つ入れます。さらに入れ子を増やしていく場合には半角スペースをその分4つ増やしていきます。

- 通常の箇条書き
    - 通常の箇条書き
    - 通常の箇条書き
- 通常の箇条書き
- 通常の箇条書き

また、箇条書きで段落を表現したい場合があります。その場合には、1行空けて記述します。複数段落になる場合には、2段落目以降は半角スペースを4つ入れます。これは後述の番号付き箇条書きでも同じ形式になります。

- 箇条書き。1段落目。

    上記箇条書きの2段落目。

    上記箇条書きの3段落目。

- 箇条書き。1段落目。

    - 入れ子の箇条書き。1段落目。

        入れ子の箇条書き。2段落目。

- 箇条書き。1段落目。

順序付きのある箇条書き

順序付きのある箇条書きと一概に言っても、順序付けの表記としてアラビア数字（1, 2, 3,……⁠）⁠、ローマ数字（i, ii, iii,……⁠）⁠、半角英字（a, b, c,……）など、いろいろありますが、通常のMarkdownではアラビア数字のみに対応しています。

アラビア数字の順序付けがある箇条書きは次のように書けます。.のあとには半角スペース1つ以上入れる必要があります。

段落。段落。段落。段落。段落。

1. Plan
2. Do
3. Check
4. Action

段落。段落。段落。段落。段落。

なお、gihyo.jpでは通常のMarkdownでは不可能な、次のような飛び番の記述が可能としています。

2. 🦍
3. 📯
5. 💎
6. 🦫

注意：Markdownの記法的には1のみを使って順序付きの箇条書きを記述することもできます。次の例は、上記の例と同じ扱いになります（自動で採番されるため便利ですが、本文上で言及する際に分かりにくいため、筆者としては通常の文書ではお勧めしません⁠）⁠。

1. Plan
1. Do
1. Check
1. Action

アラビア数字以外の順序付き箇条書き〘拡張構文〙

順序付けのある箇条書きで、アラビア数字しか使えないのは不便です。そこでgihyo.jpでは、次のようにローマ数字、アラビア文字、丸数字を使って記述することも許容しています。記述方法は、順序付きのない箇条書きの記法を使い、その直後に、その数字を書いて、その直後に丸数字以外では.を書き、そして半角スペースを入れるかたちをとっています。

1. 項目1
2. 項目2
    - i. 項目2-i
    - ii. 項目2-ii
        - a. 項目2-ii-a
        - b. 項目2-ii-b
        - c. 項目2-ii-c
    - iii. 項目2-iii
3. 項目3

- ① 順序付きの箇条書き
- ② 順序付きの箇条書き
- ③ 順序付きの箇条書き

記述リスト〘拡張構文〙

記述リストはもともとのMarkdownでは定義されていません。PHP Markdown Extraの拡張構文が使われることがあり、gihyo.jpでもこの記述方法が使えます。もちろんHTMLで記述リストを書いても構いません。

ノート：長めの記述リストの場合、記述リストではなく見出しを使うべきかで迷うことがあるかもしれません。ポイントとして挙げられるのは、記述リストの後が通常の本文に戻るかどうか（記述リストにする⁠）⁠、目次として掲載したほうが良いか（見出しにする）になるでしょう。

PHP Markdown Extra形式の記述リストは用語を書いて、その次の行の行頭に半角の:を書き、半角スペース3つ入れます。その後、説明を書きます。そして、次の用語の前には空白行を入れます。

段落。段落。段落。段落。段落。段落。

用語1
:   説明。説明。説明。説明。説明。説明。説明。

用語2
:   説明。説明。説明。説明。説明。説明。説明。

段落。段落。段落。段落。段落。段落。

用語に対して説明の種類が異なるものを複数入れる場合には、次のように、:で始まる行を増やします。

用語1
:   説明1-1。説明1-1。説明1-1。説明1-1。
:   説明1-2。説明1-2。説明1-2。説明1-2。

用語2
:   説明2。説明2。説明2。説明2。説明2。説明2。説明2。説明2。

上記は説明文が端的な場合です。説明文を段落として、複数段落入れる場合には、次のように全体を1行空きにし、かつ2段落目以降の段落は行頭4文字分の半角スペースを入れて書きます。

通常段落。通常段落。通常段落。通常段落。通常段落。

用語1

:   説明1段落目。説明1段落目。説明1段落目。説明1段落目。

    説明2段落目。説明2段落目。説明2段落目。説明2段落目。

用語2

:   説明1段落目。説明1段落目。説明1段落目。説明1段落目。

    説明2段落目。説明2段落目。説明2段落目。説明2段落目。

通常段落。通常段落。通常段落。通常段落。通常段落。

箇条書きの見出しを表現する際、記述リストと組み合わせて記述する方法があります。

通常段落。通常段落。通常段落。通常段落。通常段落。

箇条書きの見出し（として使われる記述リスト）
:   - 箇条書き。
    - 箇条書き。
    - 箇条書き。

通常段落。通常段落。通常段落。通常段落。通常段落。

コードブロック⁠、端末（ターミナル）表示

コードブロックは、もともとのMarkdownでの書き方（インデント形式）よりも、CommonMark等で採用されている拡張構文（フェンス形式）のほうが広く利用されているようです。インデントを入れるのに手間がかかることと、コード自体のインデントと混同してしまうことが要因でしょう。

インデント形式

もともとのMarkdownでは次のように、対象段落よりも半角スペース4つ、またはタブ1つ入れることでコードブロックを記述できます。

段落。段落。段落。段落。段落。

    document.write('Hello! World')

段落。段落。段落。段落。段落。

フェンス形式（バッククォート）〘拡張構文〙

現在よく利用されているのが3つのバッククォート```で囲う形で、筆者としてもこの記法をお勧めします。なお、開始の``` の直後に拡張子（または言語名）を入れると、コードブロックの言語を設定できます（code要素にclass="language-拡張子"が付きます⁠）⁠。もしコードハイライトに対応していれば色付けされます。

段落。段落。段落。段落。段落。

```js
document.write('Hello! World')
```

段落。段落。段落。段落。段落。

ノート：仕様によっては開始の```後に{}で囲み、その中にCSSセレクタを記述できます。

フェンス形式（チルダ）〘拡張構文〙

~~~で囲って表現することもできます。なお、開始の~~~の後に拡張子（または言語名）を入れると、バッククォート形式と同じようにコードブロックの言語を設定できます。もしコードハイライトに対応していれば色付けされます。

段落。段落。段落。段落。段落。

~~~js
document.write('Hello! World');
~~~

段落。段落。段落。段落。段落。

行番号付きのコードブロック

gihyo.jpでは構文を拡張して、行番号付きのコードブロックを表示できるようにしています。その場合には、開始の```または~~~の後に{start="開始行番号"}を入れます。なお、行番号の表示はCSSで行われるため、ブラウザで表示したときには選択できないことに注意してください。

段落。段落。段落。段落。段落。

```js {start="1"}
document.write('Hello! World')
```

段落。段落。段落。段落。段落。

コードブロックのキャプション〘拡張構文〙

gihyo.jpではコードブロックのキャプションを、次のようにコードブロック直前の段落として記述します。その際、コード（またはリスト、プログラム、Code）を接頭語にして、区切り文字（スペース、句点（。⁠）⁠、コロン）を入れた後に、実際のキャプションを記述します（この接頭語はその直後に番号が付いているときのみ表示します⁠）⁠。

段落。段落。段落。段落。段落。

コード キャプション ★「コード」の文字列は実際には表示されない★

```js
console.log('Hello! World')
```

段落。段落。段落。段落。段落。

コード1 キャプション ★「コード1」の文字列は実際に表示される★

```js
console.log('Hello! World')
```

段落。段落。段落。段落。段落。

またファイル名を明記する場合には、キャプションの冒頭、"で囲った文字列がある場合、ファイル名として扱います。その場合、実際のキャプションとの間にはスペースを入れてください。

端末（ターミナル）表示の指定〘拡張構文〙

gihyo.jpでは、端末画面の指定はコードブロックを利用します。その際、コードハイライトの記号としてsamp（またはshell、console）を付けます。これにより、背景が黒く、文字が白色で表示されるようになります。

また、端末表示にキャプションを付ける場合には端末やターミナル、Terminalを接頭語にしてください（この接頭語は番号が付いていると気のみ表示します⁠）⁠。

段落。段落。段落。段落。段落。

```samp
$ npm install cgm
```

段落。段落。段落。段落。段落。

端末 MarkdownをHTMLに変換する ★「端末」は表示されない★

```samp
$ cgm convert example.md
```

段落。段落。段落。段落。段落。

ノート： shell、consoleを使った場合にはコードハイライトが効きます。ただし、そのコードハイライトが完全ではないため、変に色がついてしまう可能性があります。よって基本的にはsampを使うのをお勧めします。

引用ブロック

引用（ブロック）は、行頭に>を書き、直後に半角スペースを入れた後に、引用文を書きます。引用する段落が続く場合、Markdownの空き行にも>を入れます。

なお、引用内に見出しがある場合、gihyo.jpにおいては、現在の本文の見出しレベルよりも一つ小さい見出しを使うようにしてください。

### 本文見出し

段落。段落。段落。段落。段落。段落。段落。

> #### 引用文内見出し
>
> 引用。引用。引用。引用。引用。引用。引用。
>
> 引用。引用。引用。引用。引用。引用。引用。

段落。段落。段落。段落。段落。段落。段落。

引用元の表記〘拡張構文〙

引用には引用元の明記が必須です。しかしながらMarkdownでの表現方法は規定されていません。gihyo.jpでは次のように引用元：や出典：の段落を引用ブロック直後に入れる形を取っています。この「引用元：」や「出典：」は表示されます。

段落。段落。段落。段落。段落。段落。段落。

> 引用。引用。引用。引用。引用。引用。引用。

引用元：『書名』（技評太郎 著、技術評論社、2016；p. 20）

段落。段落。段落。段落。段落。段落。段落。

画像

Markdownファイルでは画像の配置を記述できます。次のように、画像の閲覧ができない場合の代替文と、画像ファイルを記述します。[]の中が代替文で、()の中に画像ファイルのパスを書きます。また任意に、画像ファイルのパスの後に半角スペースを入れて"文字列"を入れることで、title属性とその値を設定できますが、基本的に使うことはないでしょう。

段落。段落。段落。段落。段落。段落。

![Twitterのタイムラインでは上から下に投稿が流れます。](twitter-timeline.png)

段落。段落。段落。段落。段落。段落。

![Twitterのページでは左側にメニュー、右側にタイムラインが表示されます。](./twitter-webpage.png "Twitterのウェブサイトより")

ピタゴラスの定理は![a^2+b^2=c^2](image/pythagorean.png)と書けます。

なお、手順解説時にあわせて掲載するキャプチャ画像など、本文中にきちんと画像の説明がある場合には、代替文はなくても構いません。また、後述のキャプションがある場合には、代替文字なしを現在許容しています（キャプションと同じような文字列しか記述しないのであれば、冗長だという判断によるものなので、代替文が記述されることに越したことはありません⁠）⁠。

また、gihyo.jpの本文幅は現在680px相当です（もちろんスマートフォンで閲覧時はこの値よりも狭くなります⁠）⁠。本文幅よりも大きな画像は縮小されて表示される点に注意してください。

ノート：base64エンコード（data:image/jpeg;base64,...）でsrc属性に画像データを直接埋め込む手法もありますが、gihyo.jpでは非推奨です。

ノート：コードブロックを利用して作図を記述できるPlantUMLやMermaidなどの拡張構文もあり、利用することは問題ありませんが、gihyo.jpでは画像として配置します。

ノート：gihyo.jpでは、段落が1つのみ画像のみで構成されている場合、HTML的に段落（p要素）ではなく図版（figure要素）として処理します。また画像自体は、横幅（width属性）と縦幅（height属性⁠）⁠、遅延ロード（loading属性⁠）⁠、非同期デコード（decoding）属性もあわせて指定するようにしています。なお、文章中にも画像を埋め込めんだ場合に行間が大きくなりすぎないように、段落内の画像の高さにはCSSで最大値が指定されることに注意してください。

画像サイズの指定〘拡張構文〙

ブラウザで表示する際、画像サイズを指定したい場合があります。gihyo.jpでは独自の構文を利用しています。

画像サイズを指定する場合は、画像のtitle属性の値を利用します。次のように指定することで、横幅を指定でき、縦幅は自動的にそれに合わせた値を設定します。

![Alternative text.](source.jpg "リサイズ：100px")
★実サイズが横幅400px、縦幅300pxであれば、横幅100px、縦幅75pxのサイズで表示される。★

![Alternative text.](source.jpg "resize: 50%")
★実サイズが横幅400px、縦幅300pxであれば、横幅200px、縦幅150pxのサイズで表示される。★

画像のキャプション〘拡張構文〙

キャプション付き画像をMarkdownで記述する方法は規定されていません。gihyo.jpでは、画像のみで構成されるMarkdown段落に対して、その直前に図1 キャプションのように入れる形を取っています。

段落。段落。段落。段落。段落。

図1 キャプション

![代替文](image.jpg)

段落。段落。段落。段落。段落。

キャプション文かの具体的な判断は、画像のみで構成される段落の直前か直後の段落が冒頭、図または写真またはイラスト（英語のFigure、Photo、Illustも可）の文字列で始まっていて、その文字列の後にスペース、コロン、句点（。）のいずれかが入力されている必要があります（判断処理はもう少し複雑なのですがこの把握で特に問題ないはずです⁠）⁠。なお、冒頭の文字列の直後に、図番号（およそ0-9A-Z.-で構成される文字列）を任意で入れることができます。

ノート：キャプションを代替文に入れる記法もよく見かけます。これについては原稿上そのままで構いません。変換をかけるようにします。

段落。段落。段落。段落。段落。

![図1 キャプション](image.jpg)

段落。段落。段落。段落。段落。

また、原稿上、図の番号が付いていなくても構いません。よって、次のような記述でも特に問題ありません。

段落。段落。段落。段落。段落。

![キャプション](image.jpg)

段落。段落。段落。段落。段落。

さらに、title属性にキャプションを付ける方法も許容しています。この場合は前項で取り上げた、画像サイズの指定を適用できません。

段落。段落。段落。段落。段落。

![](image.jpg "キャプション")

段落。段落。段落。段落。段落。

ファイル内でキャプションの付け方を統一してください。

表組み〘拡張構文〙

表組みは、もともとのMarkdownでは定義されていません。拡張構文を使うか、または素直にHTMLで書きます。セル内が非常に複雑になるものは素直にHTMLを使うのが良いでしょう。

Pandoc’s Markdownのドキュメントに表組みのいくつかの拡張構文がまとめられています。パイプテーブル形式の拡張構文を、gihyo.jpでは利用しています。

パイプテーブル形式

表組みで、たぶんもっとも利用されている拡張構文がパイプテーブルでしょう。次のように書きます。具体的には|でセルの範囲を表します（セル内部の先頭または末尾の半角スペースは無視されます⁠）⁠。そして、表見出し行と通常セル行群の区切りを示すために、区切りの各セルは-のみのセルの行を作ります。

段落。段落。段落。段落。段落。

| h1  | h2  | h3  |
| --- | --- | --- |
| a   | b   | c   |
| d   | e   | f   |

段落。段落。段落。段落。段落。

ノート：セル内での改行は、HTMLの タグを使ってください。そのほかの改行表現を伴う複雑なセルもHTMLで表現する必要があります。

また区切りセルで:を添えることで、列セル（td要素）を左、中央、右のそれぞれに寄せることができます。次の例では、それぞれのセルも寄せ方を指定したとおりに寄せて記述していますが、その必要はありません。

| 左寄せ  | 中央寄せ   | 右寄せ   |
| :----- | :------: | -----: |
| a      |    b     |      c |
| d      |    e     |      f |

なお、表として一番外側セルの|は省略できるため、次のようにも書くことができます。

段落。段落。段落。段落。段落。

 h1  | h2  | h3
:--- |:---:| ---:
 a   | b   | c
 d   | e   | f

段落。段落。段落。段落。段落。

MultiMarkdownのパイプテーブル

パイプテーブルを拡張したものがMultiMarkdownのパイプテーブルです。これを利用することにより、セルの結合や表見出しのない表組みが表現できます。gihyo.jpでは対応していますが、そこまで広く使われているわけではないことに注意してください。

セルの結合

セルの結合は次のように書けます。具体的には^^を使うことで上とセルと結合でき、セルの中身がない場合には左のセルと結合できます。

| a | b | c| d |
|---|---|---|---|
| y | n | y | y |
| n |^^ | n | y |
| y | n | y    ||

表見出しのない表

また、表見出し（th要素）がない表組みは次のように書けます。

|---|---|---|---|
| y | n | y | y |
| n |^^ | n | y |
| y | n | y    ||

行セルに見出しがある表

Microsoft DocsのMarkdownでは次のような拡張構文として使っており、d、e、fをth要素として扱います。**を使って表現するのが良いかは判断が分かれるかと思いますが、大きくは問題ないと考えてgihyo.jpでもこれに倣うことにしました。

|       | a | b | c |
|-------|---|---|---|
| **d** | y | y | y |
| **e** | y | y | y |
| **f** | y | y | y |

表のキャプション

gihyo.jpでは表のキャプションを、表組みの直前の段落として記述します。接頭語としては表またはTableを使います。

段落。段落。段落。段落。段落。

表1 キャプション

| 表見出し1 | 表見出し2 |
|---------|---------|
| 🐈      | 🌾      |
| 🐩      | 🍎      |

段落。段落。段落。段落。段落。

数式〘拡張構文〙

数式ブロックは、行頭$$から次に行頭の$$が書かれている範囲内を指します。この中で、Tex記法で数式を書きます。gihyo.jpではMathJaxを利用して描画した画像を埋め込んでいます。MathJaxのTexサポートについては公式サイトを参照してください。

段落。段落。段落。段落。段落。

$$
E = MC^2
$$

段落。段落。段落。段落。段落。

段落中でも数式が書けます。文章中では$で囲みます。

ピタゴラスの定理は$a^2+b^2=c^2$と書けます。

ノート：TeXの書き方は、技術評論社から『LaTeX2ε美文書作成入門』も刊行されていますので、参考にしてください。

動画

動画は次のように記述します。キャプションが必要な場合には、その直前の段落で「動画」から始まる段落を記述します。

段落。段落。段落。段落。段落。

動画 サンプル動画

<video controls width="680" height="383">
<source src="example.mp4" type="video/mp4">
</video>

段落。段落。段落。段落。段落。

YouTubeの動画を埋め込む場合には、その動画のページの共有ボタンに記載さる埋め込み用のHTMLを、次のように貼り付けてください。

段落。段落。段落。段落。段落。

動画 サンプル動画

<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/XXXXXXXXXXX" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</figure>

段落。段落。段落。段落。段落。

意味付けしたブロック〘拡張構文〙

いくつかの仕様では注意文など、意味のある文章の範囲を指定するために拡張構文を規定して使っています。もちろん素直にHTMLを使ってもいいでしょう。gihyo.jpでは「HRサンドイッチ記法」という独自の拡張構文を使っています。

HRサンドイッチ記法

HRサンドイッチ記法は、Markdownの構文を拡張しようとはせずに語彙を利用して拡張した記法です。見出しなし話題転換の編集記号（3種類あるが同一の記号を使う必要がある）を使って範囲を指定して、その範囲内の最初の文字列を特定のキーワードから始めることで、Markdownの既存記法に配慮しつつ、意味付けしたブロックを作ります。

段落。段落。段落。段落。段落。段落。段落。

---

**注意：**注意段落。注意段落。注意段落。注意段落。

注意段落。注意段落。注意段落。注意段落。注意段落。

---

段落。段落。段落。段落。段落。段落。段落。

上記では注意：を**で囲っていますが、囲わなくても構いません。また注意段落が1行の場合には、話題転換の編集記号を省略することもできます。つまり、次のようにも書けます。

段落。段落。段落。段落。段落。段落。段落。

注意：注意段落。注意段落。注意段落。注意段落。

段落。段落。段落。段落。段落。段落。段落。

見出しのないブロック

gihyo.jpでは、見出しのない囲みブロックとして、以下の語句を使っています。

まずは、一つの段落で済むものが多いものとして、以下のものがあります。

通常段落。通常段落。通常段落。通常段落。通常段落。

警告：警告文。Warningでも構いません。

注意：注意文。Cautionでも構いません。

お知らせ：お知らせ文。通知や通告、Noticeでも構いません。

情報：情報文。参考情報、Informationでも構いません。

ノート：ノート文。Noteでも構いません。

メモ：メモ文。Memoでも構いません。

助言：助言文。コツ、Tipsでも構いません。

ポイント：ポイント文、要点、Pointでも構いません。

通常段落。通常段落。通常段落。通常段落。通常段落。

複数段落になりがちなものとして、以下のものがあります。

通常段落。通常段落。通常段落。通常段落。通常段落。

---

補足情報：内部一段落目。内部一段落目。内部一段落目。内部一段落目。内部一段落目。

内部二段落目。内部二段落目。内部二段落目。内部二段落目。内部二段落目。

---

通常段落。通常段落。通常段落。通常段落。通常段落。

最初が見出しのブロック

意味付けしたブロックは、最初の段落は見出しにすることが可能です。以下のようなものがあります。

コラム

通常段落。通常段落。通常段落。通常段落。通常段落。

---

### Column：コラムタイトル

コラム本文。コラム本文。コラム本文。コラム本文。コラム本文。

---

通常段落。通常段落。通常段落。通常段落。通常段落。

プロフィール

---

### プロフィール：技評太郎（ギヒョウタロウ）

![著者近影](author.jpg)

プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。プロフィール文文。

- Twitter：[@gihyojp](https://twitter.com/gihyojp)

---

ノート：他サイトで見かける、意味付けしたブロックの拡張構文を参考までに記載しておきます。

コンテナ記法

よく利用されている形式にコンテナ記法があります。国内のウェブサービスでもこのような記法が使われていることを見かけます。

段落。段落。段落。段落。段落。

::: Notice
コメント。コメント。コメント。コメント。
:::

段落。段落。段落。段落。段落。

Admonition記法

Markdownとは異なるreStructuredTextからの流れでPython-Markdownなどが採用している、Admonitionと呼ばれる記法があります。Admotionでは!!!と4つ空きインデントを利用して構成します。

段落。段落。段落。段落。段落。

!!! Notice

    コメント。コメント。コメント。コメント。

段落。段落。段落。段落。段落。

GitHub記法

GitHubでは現在次の形が検討され、現在GitHub内で利用できます（ほぼ似た構文を採用しているのがMDNのSpecial attentionです⁠）⁠。引用の編集記号を利用するのが懸案点ではありますが、GitHubの影響力から使われるようになるかもしれません。

段落。段落。段落。段落。段落。

> [[NOTE]
> ノート文。ノート文。ノート文。ノート文。ノート文。ノート文。

段落。段落。段落。段落。段落。

スタイル〘拡張構文〙

Markdownでは各要素に対してスタイルを設定するための基本構文はありません。よく使われている拡張構文として、行末に{CSSセレクタ}と指定する方法が使われます。複数指定する場合は間に半角スペースを入れます。例えば、次のように書きます。

段落。段落。段落。段落。段落。 {#name}

段落。段落。段落。段落。段落。 {.bar1 .bar2}

箇条書きや表に対してもスタイルを適用することができます。その場合にはそれらの直後の行に{スタイル}を記述します。

style要素を使ってCSSを付属させることで、スタイルを適用することもできます。

文書設定（メタ情報）〘拡張構文〙

Markdownファイルを扱うプログラムに、そのファイルの文書設定（メタ情報）を渡せると便利です。しかしMarkdownではファイル内で文書設定を指定する基本構文はありません。

文書設定を行なう場合に拡張構文としてよく使われるのが、Markdownファイルの冒頭にYAMLを記述する形式です。具体的にはファイル1行目に---のみの行を書いて、次行以降にYAMLのハッシュ形式（キーワード: 値）で設定を書き、最後に---のみの行を書きます。もちろん、この部分は本文としては扱いません。

たとえば、次のように文書設定を書くことで、キーワードであるurl（実際の記事URL⁠）⁠、author（執筆者名⁠）⁠、tag（タグ）を指定できます。なお、キーワードは仕様によって異なります。

---
title: 記事タイトル
author: 技評太郎
tag: hoge, fuga
url: https://gihyo.jp/article/2022/08/alias
---

本文。本文。本文。本文。本文。本文。

ノート：gihyo.jpではメタ情報のtitleと見出しレベル1は両方とも記事タイトルを指します。両方記述されている場合、メタ情報のtitleを優先して使います。

おわりに

本稿ではgihyo.jpのMarkdown記法方法を解説しました。Markdownに対応しているエディタを利用することで、構文（編集記号）がハイライトされたり、HTMLのプレビューを見ながら作業できたりする場合も多いですが、さらに構文チェックツール（markdownlintなど）の併用もお勧めです。

また、Markdownはあくまでテキスト文書のための構文の一つです。このような構文は他にもAsciiDocやreStructuredText、Org Modeなどがあることに留意してください。冒頭に触れたとおり、Markdownはそれぞれ独自の拡張記法が多いため、互換性を気にしないといけません。よってMarkdownでは、その出力であるHTMLを最終的に見ることになるでしょう。