ふだん Markdown を書く技術者のための reStructuredText 文法まとめ

2018/03/23Markdown reStructuredText

ふだんは Markdown を書いていて、稀に reStructuredText を書く必要がある技術者（私です）のための reStructuredText 文法まとめです。

reStructuredText のすべてを網羅するのではなく、あくまで「 Markdown にある機能を reStructuredText で使いたい」という状況を想定した上での簡易的なまとめです。

reStructuredText の詳細を本格的に学びたい場合は次の 2 つのページを参照することをおすすめします。

「 Markdown なら書き方がわかっているんだけど、 reStructuredText でどう書けばいいかわからないので、いちいち検索してしまう」という方のお役に立てば幸いです。

パラグラフ

Markdown:

これはひとつの段落です。
1 つだけの改行は HTML に変換されるときに削除されます。

これは別の段落です。

reStructuredText:

これはひとつの段落です。
1 つだけの改行は HTML に変換されるときに削除されます。

これは別の段落です。

パラグラフ（段落）のルールはほぼ共通です。

1 つだけの改行は削除されて、連続した改行（空行）が段落の区切りになります。

見出し

Markdown:

# h1

## h2

### h3

#### h4

##### h5

###### h6

reStructuredText:

h1
##

h2
==

h3
--

h2 again
========

h1 again
########

Markdown では行頭に # を付けた行が見出しになります。 # の数で見出しレベルを指定します。

reStructuredText は、区切り文字（ #*=-^" ）のどれかを下に並べて装飾した行が見出しになります。

Sphinx の場合は区切り文字を別のものに変えると見出しレベルが変わります。例えば h1 に相当するものに # を使っている場合に # 以外のものを使うとそこが h2 になり、以下同様に h3 〜 h6 とレベルが落ちていきます。

上の例では # が h1 で = が h2 になっていますが、ここは特に決まっていません。自動的に、同一ファイルの先頭にある見出しが h1 になり、区切り文字が変わる度に見出しレベルが下がっていきます。

次のように、見出しの次の行だけでなく前の行にも区切り文字を並べてもよいですが、ここは必須ではありません。

reStructuredText:

##########
This is h1
##########

装飾のための区切り文字の行の長さは、最低でも対象の見出し行と同じにする必要があるようです。これは等幅ではないフォントを使っているときに少し厄介です。

「上の例では # が h1 で = が h2 になっていますが、ここは特に決まっていません」と述べましたが、 Python のドキュメンテーションスタイルガイドでは次の順番で使うことがルールとなっているようです。

# 部（ h1 に相当）（見出し行の上にも付ける）
* 章（ h2 に相当）（見出し行の上にも付ける）
= セクション（ h3 に相当）
- サブセクション（ h4 に相当）
^ サブサブセクション（ h5 に相当）
" パラグラフ（おそらく h6 に相当）

以下参考。

7. Documenting Python — Python Developer's Guide

このルールに従って書いたサンプルは次のとおりです。

reStructuredText:

####
h1
####

****
h2
****

h3
====

h4
----

h5
^^^^

h6
""""

個人的には、特に深い理由がなければこれに従っておくのがよいのではないかと思います。

順序なしリスト

Markdown:

* 第 1 四半期
    * 睦月
    * 如月
    * 弥生
* 第 2 四半期
    * 卯月
    * 皐月
    * 水無月

reStructuredText:

* 第 1 四半期

  * 睦月
  * 如月
  * 弥生

* 第 2 四半期

  * 卯月
  * 皐月
  * 水無月

reStructuredText の順序なしリストは Markdown のものとよく似ていますが、入れ子にしたい場合は、親子間に空行を挟み、親要素のテキストの先頭と子要素の * のインデントを合わせる必要があります。

順序付きリスト

Markdown:

1. Alpha
2. Bravo
    1. Charlie
    1. Delta

reStructuredText:

1. Alpha
2. Bravo

   1. Charlie
   2. Delta

順序付きリストも、順序無しリストと同様、入れ子にする場合のルールが Markdown とは異なります。入れ子にするには、親子間に空行を挟み、親要素のテキストの先頭と子要素の数字 1. の左端のインデントを合わせる必要があります。

Markdown にあるような自動採番を使いたい場合は、 #. を使用します。

reStructuredText:

#. Alpha
#. Bravo

   #. Charlie
   #. Delta

定義リスト

Markdown の方言の中には定義リスト（ definition list ）をサポートしているものもあり、記法は次のとおりとなっています。

Markdown:

（言葉）
: （言葉の意味の説明）

塞翁が馬
: 幸福か不幸かはすぐにはわからないので、すぐに一喜一憂すべきではないということ。

reStructuredText にはデフォルトで定義リストが備わっています。

reStructuredText:

（言葉）
    （言葉の意味の説明）

塞翁が馬
    幸福か不幸かはすぐにはわからないので、すぐに一喜一憂すべきではないということ。

    このように空行を挟むことで、段落を分けることもできます。

空行を挟まずに対象のテキストの次の行からインデントされた行を書きます。説明には空行を入れて複数のパラグラフを入れることもできます。

引用ブロック

Markdown:

Martin Luther King, Jr. said.

> I have a dream that one day on the red hills of Georgia, the sons of former slaves and the sons of former slave owners will be able to sit down together at the table of brotherhood.
>
> I have a dream that one day even the state of Mississippi, a state sweltering with the heat of injustice, sweltering with the heat of oppression, will be transformed into an oasis of freedom and justice.

reStructuredText:

Martin Luther King, Jr. said.

    I have a dream that one day on the red hills of Georgia, the sons of former slaves and the sons of former slave owners will be able to sit down together at the table of brotherhood.

    I have a dream that one day even the state of Mississippi, a state sweltering with the heat of injustice, sweltering with the heat of oppression, will be transformed into an oasis of freedom and justice.

単純に前後のパラグラフよりもインデントを下げれば blockquote での引用になります。

テーブル

Markdown:

| 犬種 | 説明 |
| --- | --- |
| 芝犬 ｜ 芝のような毛並みの犬。 |
| 秋田犬 ｜ 秋田あたりにいそうな犬。 |

reStructuredText:

==== =====
犬種  説明
==== =====
芝犬  芝のような毛並みの犬。
秋田犬 秋田あたりにいそうな犬。

テーブルの記法はいくつかあります。

上のコードはシンプルな記法で書いたものです。シンプルな記法で書いたテーブルには「最初の列では改行ができない」等の制限があります。

例えば、 csv-table というディレクティブ（命令）を使用すれば csv 形式でテーブルを書くことができます。

.. csv-table::
    :header: "犬種", "説明"
    :widths: 15, 40

    "芝犬","芝のような毛並みの犬。"
    "秋田犬","秋田あたりにいそうな犬。"

Markdown でも reStructuredText でも、日本語文字を含むテーブルを書くのが辛いところは同じです。

改行

Markdown:

あかあかと
日は難面も
あきの風

reStructuredText:

| あかあかと
| 日は難面も
| あきの風

Markdown の場合は行末にスペースを 2 つを入れると改行 <br> になりますが、 reStructuredText の場合は行頭に | を置いたパラグラフにおいて改行が保たれます。

チェックリスト

一部の Markdown エンジンはチェックリストのための記法を用意しています。

Markdown:

- [ ] リンゴを買う
- [ ] イチゴを買う

reStructuredText:

（無し）

reStructuredText にはチェックリストは備わっていないようです。

コードブロック

Markdown:

画面に出力をするプログラムを書いてみましょう。

```
print('Hello, world')
```

Hello world と出力されたでしょうか。

reStructuredText:

画面に出力をするプログラムを書いてみましょう

::

    print('Hello, world')

Hello world と出力されたでしょうか。

reStructuredText では、 :: だけの行を書いてインデントをすると、その部分がコードブロックとして扱われます。

次のように、 :: は直前のパラグラフにくっつけることもできますが、上の形が基本形と覚えておくのがよいかと思います。

reStructuredText:

画面に出力をするプログラムを書いてみましょう ::

    print('Hello, world')

reStructuredText:

画面に出力をするプログラムを書いてみましょう::

    print('Hello, world')

ちなみに、 :: を直前のパラグラフにくっつける場合は、 :: の直前の文字が空白文字かどうかで : ひとつが出力されるかどうかが変わります。細かいです。

画像

Markdown:

![alt テキスト](画像の URL )

reStructuredText:

.. image:: 画像の URL
    :alt: alt テキスト

.. image:: capture.png
    :alt: 使用方法の説明のためのキャプチャ画像です。

画像の挿入には image ディレクティブを使います。

上でも csv-table ディレクティブのサンプルをあげましたが、ここでディレクティブについてかんたんに説明をしておきます。 reStructuredText において「ディレクティブ」（ directive ）とは、特定の要素を挿入するための汎用的な仕組みのことです。

ディレクティブは次のフォーマットで記述します。

.. （ディレクティブタイプ） :: ディレクティブ
    追加ブロック

デフォルトでは、例えば次のようなディレクティブが用意されています。

admonition
image
figure
topic
sidebar
parsed-literal
code
math
rubric
epigraph
highlights
pull-quote
compound
container
table
csv-table
list-table
contents
sectnum (section-numbering)
header
footer
target-notes
footnotes
citations

ディレクティブの詳細な説明はこの記事のスコープ外なのでこれ以上の説明はしません。興味のある方は次のページ等をご覧になってみてください。

directives | reStructuredText Markup Specification

リンク

Markdown:

[アンカーテキスト](リンク先 URL)

reStructuredText:

`アンカーテキスト <リンク先 URL>`_

reStructuredText のリンクは上の形を使用します。

リンク先 URL をファイルの末尾でまとめて指定したい場合は、次のようにすると OK です。

reStructuredText:

詳しくは `こちら`_ で検索してください。

.. _こちら: リンク先 URL

同一のドキュメント内のリンクを付けたい場合に使える、 URL を使わない方法も用意されています。

:ref: | Inline markup — Sphinx documentation

強調

Markdown:

**これは strong 相当です**

*これは em 相当です*

reStructuredText:

**これは strong 相当です**

*これは em 相当です*

強調の仕方は reStructuredText は Markdown とほぼ同じです。

ただし、 Markdown では * （アスタリスク）の他に _ （アンダースコア）も強調に使うことができますが、 reStructuredText で使えるのは * のみとなっています。

インラインコード

Markdown:

ここで変数 `f` はファイルハンドラへの参照となっています。

reStructuredText:

ここで変数 :code:`f` はファイルハンドラへの参照となっています。

インラインで <code> タグを使いたい場合は :code: の後にバッククォートを使って対象の文字列を挟みます。

似たものとして、バッククォート 2 つで文字列を挟んだ「リテラル」（ literal ）と呼ばれるものがあります。

reStructuredText:

全角スペースのユニコードは ``\U3000`` です。

リテラルにはマークアップ等の装飾が行われずそのまま出力されます。バックスラッシュのエスケープ等が行われないので、上の例のようにユニコード等を記述したいときに便利かもしれません。

GitHub Flavored Markdown

Markdown のメジャーな方言である GitHub Flavored Markdown で利用できるパターンをいくつか取り上げます。

シンタックスハイライティング

Markdown:

```css
.main .date {
  text-align: right;
}
```

reStructuredText:

.. code-block:: css

   .main .date {
     text-align: right;
   }

GitHub Flavored Markdown ではバッククォートの行でシンタックスのタイプを指定できますが、それと同じこと reStructuredText でやる場合は code-block ディレクティブを使います。

reStructuredText のコードブロックには、行番号を表示したり特定の行を強調したりできる強力なオプションが豊富に用意されているので、コードブロックを使いたい場合はそれらを確認しておくとよいでしょう。

Showing code examples — Sphinx documentation

打ち消し線

Markdown:

~~間違い~~

reStructuredText:

（無し）

reStructuredText には打ち消し線はデフォルトではありません。どうしても使いたい場合は、打ち消し線のための独自 role を定義するとよいでしょう。具体的なやり方は、次の Stack Overflow のページの質問と回答が参考になります。

restructuredtext - ReST strikethrough - Stack Overflow

絵文字

Markdown:

:smiley:

reStructuredText:

（無し）

GitHub Flavored Markdown では :絵文字を示す文字列: という形で絵文字を利用することができますが、 reStructuredText には同等の機能はありません。

絵文字は直接挿入すればよいのですが、どうしても同じようなことをやりたい場合は .. |置換対象| replace:: 置換後の文字列 で定義できる substitution パターンを定義して利用するようにするとよいかもしれません。

reStructuredText:

This is great |smiley|

Thank you |smiley|

.. |smiley| replace:: 😊

|smiley| の部分はすべて指定された絵文字に置換されます。

substitution について詳しく知りたい場合は次のページが参考になります。

Substitution Definitions | reStructuredText Markup Specification

以上です。

reStructuredText の文法について詳しくは以下の（公式の）ページにまとまっているので、もっと深く調べたい方はそちらをご覧ください。

目次

パラグラフ

見出し

順序なしリスト

順序付きリスト

定義リスト

引用ブロック

テーブル

改行

チェックリスト

コードブロック

画像

リンク

強調

インラインコード

GitHub Flavored Markdown

シンタックスハイライティング

打ち消し線

絵文字

参考