Markdown

この章では Julia 標準の Markdown ライブラリが実装する Markdown の構文を説明します。次の Markdown 要素がサポートされます:

インライン要素

ここで「インライン」とは、段落といったテキストブロックの中で利用できるという意味です。次の要素がインライン要素です:

太字

テキストを二つのアスタリスク ** で囲むと、内側のテキストが太字になります:

この段落には**太字**がある。

斜体

テキストを一つのアスタリスク * で囲むと、内側のテキストが斜体になります:

この段落には*斜体*の文字がある。

リテラル

書かれた通りにそのまま出力されるべきテキストは単一のバックティック ` で囲んでください:

この段落には`リテラル`の文字がある。

リテラルは変数名や関数名など Julia プログラムの要素を書くのに使ってください。

Tip

リテラルの中にバックティックを含めるには、左右のバックティックを三つにしてください:

この段落には``` `バックティック` ``` がある。

リテラルは任意の奇数個のバックティックで囲むことができ、それより小さい連続するバックティックをその中に含められます。

\(\LaTeX\)

\(\LaTeX\) を使って数式として表示されるべきテキストは二つのバックティック `` で囲ってください:

この段落には ``\LaTeX`` マークアップがある。
Tip

リテラルと同様に、数式の中で二つのバックティックを使う必要がある場合には二つより多い偶数個のバックティックを使うことができます。なお \(\LaTeX\) マークアップに単一のバックティックを含めるだけなら `` で十分です。

情報

Julia プログラムにテキストを埋め込むときは \ に対して適切なエスケープが必要なことに注意してください。埋め込まれるテキストは文字列リテラルとして解釈されるので、エスケープを適切に行って例えば "``\\LaTeX`` を含む docstring" などとしなければなりません。またこうする代わりに、非標準文字列マクロ raw を使えばエスケープせずにバックティックをテキストに含められます:

@doc raw"``\LaTeX`` を含む docstring" functionname

外部リンクと内部リンクは次の構文を使います。最初にリンクテキストを角括弧 [...] で囲んで書き、その後に URL を丸括弧 (...) に囲んで書きます:

この段落には [Julia](http://www.julialang.org) へのリンクがある。

ドキュメント内の関数/メソッド/変数に対する相互参照も追加できます。次のようにします:

"""
    tryparse(type, str; base)

Like [`parse`](@ref), but returns either a value of the requested type,
or [`nothing`](@ref) if the string does not contain a valid number.
"""

これは生成されるドキュメントで parse と nothing のドキュメント (関数の詳細な説明) に対するリンクとなります。関数の改変/非改変バージョンや似た形の関数にはリンクを追加するとよいでしょう。

情報

上記の相互参照の機能は Markdown の機能ではありません。これは Julia のドキュメントを構築するのに使われる Documenter.jl が持つ機能です。

脚注

名前付き脚注と番号付き脚注に対する参照には次の構文を使います。脚注の名前は英数字からなる一単語である必要があり、記号は使えません。

この段落には番号付き脚注[^1]と名前付き脚注[^named]がある。
情報

脚注のテキストは参照と同じページの好きな場所に書くことができます。脚注のテキストを定義する構文は後で説明されます。

トップレベル要素

次の要素はドキュメントのトップレベルもしくは他のトップレベル要素の中に書くことができます。

段落

段落は装飾のないテキストのブロックです。段落は前節で説明したインライン要素を任意の個数含むことができ、先頭と末尾に一つ以上の空行を持ちます:

これは段落です。

これは*異なる*段落です。この段落には強調されたテキストが含まれます。
改行されましたが、まだ同じ段落です。

ヘッダー

ドキュメントはヘッダーを使って異なる部分へ分割できます。ヘッダーは次の構文を持ちます:

# レベル 1
## レベル 2
### レベル 3
#### レベル 4
##### レベル 5
###### レベル 6

ヘッダーの行は段落と同様に任意のインライン要素を含められます。

Tip

単一のドキュメントでヘッダーを使い過ぎないよう注意が必要です。深い階層はドキュメントに問題があることのサインである可能性があります。文章を再構築するか、トピックごとに複数のページに分けられないかを考えてください。

コードブロック

次のようにソースコードをタブまたは四つのスペースでインデントすると、リテラルブロックとして表示されます:

これは段落です。

    function func(x)
        # ...
    end

これは別の段落です。

コードブロックは三つのバックティックでも指定できます。この形式ではコードブロックをどの言語としてハイライトするかを指定できます:

言語を指定しないコードブロック:

```
function func(x)
    # ...
end
```

`julia` という言語を指定したコードブロック:

```julia
function func(x)
    # ...
end
```
情報

インデントした形式でコードブロックを書くと言語を指定できないので、最後に示した "フェンス付きの" 形式を優先して使うべきです。

ブロッククオート

外部資料から取った文書、例えば本やウェブサイトからの引用は > を先頭に付けた連続する行で表します:

引用です:

> Julia is a high-level, high-performance dynamic programming language for
> technical computing, with syntax that is familiar to users of other
> technical computing environments.

> の後ろにスペースが一つ必要なことに注意してください。クオートされたブロックでは他のトップレベル要素およびインライン要素を利用できます。

画像

画像の構文はリンクのものと似ています。リンクの前に ! を付けると指定した URL がリンクではなく画像として表示されるようになります:

![alternative text](link/to/image.png)

リスト

箇条書きリストは *, +, - の後に要素を続けて書きます:

三つの要素からなるリスト:

  * 要素 1
  * 要素 2
  * 要素 3

* の前にある二つのスペースと後にある一つのスペースに注意してください1。

リストにはリスト・コードブロック・クオートブロックといった他のトップレベル要素を含めることができます。リストがトップレベル要素を含むなら、上下のトップレベル要素の間に空行が必要です:

別のリスト:

  * 要素 1

  * 要素 2

    ```
    f(x) = x
    ```

  * リストに含まれるリスト (サブリスト)

      + サブ要素 1
      + サブ要素 2
情報

リストの各要素の内部テキストは最初の行が揃っている必要があります。例えば上の例のフェンス付きコードブロックは "要素 2" の "要" と同じ位置までインデントされています。

順序付きリストを書くには、箇条書きリストの "バレット" 文字 (*, +, -) を正整数と `.` または `)` を続けたものに入れ替えます:

二つの順序付きリスト:

 1. 要素 1
 2. 要素 2
 3. 要素 3

 5) 要素 5
 6) 要素 6
 7) 要素 7

5 から始まっているこの例の二つ目のリストのように、順序付きリストは 1 でない数字から始めることができます。また箇条書きリストと同様、順序付きリストはトップレベル要素をネストして保持できます。

ディスプレイ数式

言語に math を指定したフェンス付きコードブロックを使えば、段落中にインライン要素として入りきらない大きな \(\LaTeX\) 数式をディスプレイ数式として表示できます:

```math
f(a) = \frac{1}{2\pi}\int_{0}^{2\pi} (\alpha+R\cos(\theta))d\theta
```

脚注

この構文は脚注参照のインライン構文と組になります。この部分も忘れずに読んでださい。

脚注テキストは次の構文で定義されます。脚注参照の構文と似ていますが、脚注のラベルの後ろに : が付いています:

[^1]: 番号付き脚注テキスト

[^note]:

    いくつかのトップレベル要素を持つ名前付き脚注テキスト

      * 要素 1
      * 要素 2
      * 要素 3

    ```julia
    function func(x)
        # ...
    end
    ```
情報

それぞれの脚注参照に対応する脚注テキストが存在することの確認はパース時に行われません。

水平線

HTML の <hr> タグに対応する水平線要素は三つのハイフン --- で表します:

水平線より上のテキスト

---

水平線より下のテキスト

表

基本的な表は次に説明する構文で作成できます。Markdown の表は機能が限られており、これまでに紹介した要素とは異なりトップレベル要素をネストして含むことができないことに注意してください ──許されているのはインライン要素だけです。表は必ずヘッダーと列の名前を持ちます。一つのセルが複数の行または列を占めることはできません。

| 列 1       | 列 2       | 列 3         |
|:---------- | ---------- |:------------:|
| 行  `1`    | 列 `2`     |              |
| *行* 2     | **行** 2   | 行 ``3``     |
情報

例にあるように、| の列は垂直に揃っている必要があります2。

ヘッダーとそれ以外を分ける行 (- を含む行) のセルの端に : を付けると、右揃え・左揃え・中央揃え (両端に : を付けたとき) を指定できます。: がない列はデフォルトで右揃えとなります。

忠告

忠告 (admonition) と呼ばれる特別な形式のブロックを使うと、特定の注意事項を目立たせて表示できます。忠告は次の !!! を使った構文で定義します:

!!! note

    これは note というタイプを持つ忠告です。

!!! warning "Beware!"

    これは warning というタイプを持つ別の忠告です。

    この忠告には `"Beware!"` というタイトルが付いています。

!!! の後に付いているのは忠告のタイプであり、小文字のアルファベット (a-z) だけからなる単語を指定できます。次の忠告のタイプには特別なスタイリングが施されます (重要度の降順に並んでいます):

忠告のタイプの後には、忠告ブロックに対する独自のタイトルを二重引用符で囲った文字列として指定できます。タイトルを指定せずに標準のタイプ (danger, warning, ...) を使うと、タイプがタイトルとして使われます。例えばタイプが note の忠告がタイトルを持たなければ、"Note" というタイトルが自動的に付与されます。

独自のブロックを定義したい場合には、次のようにします。この例では terminology ブロックが定義されています:

!!! terminology "julia vs Julia"
    厳密に言うと、Julia は言語を指し、
    julia はその標準実装を指します。

忠告は他のトップレベル要素と同様、他のトップレベル要素を含むことができます。

Markdown 構文の拡張

Julia の Markdown は通常の文字列リテラルとよく似た補間をサポートします。違うのはオブジェクトが Markdown ツリーの中に (文字列に変換されることなく) そのまま保存される点です。Markdown オブジェクトをレンダリングすると補間されたオブジェクトに対しては通常の show メソッドが呼ばれるので、通常通りオーバーライドが可能です。この設計により、どんな複雑な機能 (例えば参照) でも基本構文を壊さずに Markdown に追加できます。

理論上はパッケージから Markdown パーサー自身を自由に拡張でき、完全に独自のフレーバーを持つ Markdown も実装できます。ただ基本的にそうする必要はないでしょう。

  1. 訳注: ソースコードによると、箇条書き/番号付きリストの前にある空白はゼロ個以上三つ以下にできる。[return]

  2. 訳注: こう書いてあるが、| が揃っていなくてもパースはされる。ソースコードやテストを参照。[return]

広告
このページの文章はテキストゆれないくんを使って校正されました。