Markdown

このセクションでは、Markdown標準ライブラリによって有効にされるJuliaのMarkdown構文について説明します。サポートされているMarkdown要素は次のとおりです：

Inline elements

ここで「インライン」とは、段落などのテキストブロック内に見られる要素を指します。これには以下の要素が含まれます。

Bold

単語を二つのアスタリスク ** で囲むと、囲まれたテキストが太字で表示されます。

A paragraph containing a **bold** word.

Italics

単語を一つのアスタリスク * で囲むと、囲まれたテキストがイタリック体で表示されます。

A paragraph containing an *italicized* word.

Literals

テキストをそのまま表示する必要がある場合は、単一のバックティックで囲んでください。 ` 。

A paragraph containing a `literal` word.

リテラルは、変数、関数、または他のJuliaプログラムの部分の名前を参照するテキストを書くときに使用する必要があります。

Tip

リテラルテキスト内にバックティック文字を含めるには、テキストを囲むために1つではなく3つのバックティックを使用します。

A paragraph containing ``` `backtick` characters ```.

拡張として、任意の奇数のバックティックを使用して、より少ない数のバックティックを囲むことができます。

$\LaTeX$

テキストを数学として表示するには、$\LaTeX$構文を使用してダブルバックスラッシュで囲みます。 `` 。

A paragraph containing some ``\LaTeX`` markup.

Tip

前のセクションのリテラルと同様に、ダブルバックティック内にリテラルバックティックを記述する必要がある場合は、2より大きい偶数を使用してください。単一のリテラルバックティックを$\LaTeX$マークアップ内に含める必要がある場合は、2つの囲むバックティックで十分です。

Note

\" 文字は、テキストが Julia ソースコードに埋め込まれている場合、適切にエスケープする必要があります。例えば、 "``\\LaTeX`` の構文をドキュメント文字列に。" のように、文字列リテラルとして解釈されます。あるいは、エスケープを避けるために、@doc マクロと一緒に raw 文字列マクロを使用することも可能です：

@doc raw"``\LaTeX`` syntax in a docstring." functionname

Links

外部または内部のターゲットへのリンクは、次の構文を使用して記述できます。角括弧 [ ] で囲まれたテキストはリンクの名前であり、丸括弧 ( ) で囲まれたテキストはURLです。

A paragraph containing a link to [Julia](https://www.julialang.org).

他の文書化された関数/メソッド/変数へのクロスリファレンスを、Juliaのドキュメント内に追加することも可能です。例えば：

"""
    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 ドキュメントへのリンクも作成されます。関数の変異版/非変異版への相互参照を含めたり、似ている2つの関数の違いを強調したりすることは良いことです。

Note

上記のクロスリファレンスはMarkdownの機能ではなく、Documenter.jlに依存しており、これは基本的なJuliaのドキュメントを構築するために使用されます。

Footnote references

名前付きおよび番号付きの脚注参照は、次の構文を使用して記述できます。脚注名は、句読点を含まない単一の英数字の単語でなければなりません。

A paragraph containing a numbered footnote [^1] and a named one [^named].

Note

脚注に関連するテキストは、脚注参照と同じページ内のどこにでも記述できます。脚注テキストを定義するために使用される構文は、以下の Footnotes セクションで説明されています。

Toplevel elements

次の要素は、ドキュメントの「トップレベル」または別の「トップレベル」要素内に記述できます。

Paragraphs

段落は、上記の Inline elements セクションで定義された任意の数のインライン要素を含む可能性のあるプレーンテキストのブロックであり、その上と下に1つ以上の空白行があります。

This is a paragraph.

And this is *another* paragraph containing some emphasized text.
A new line, but still part of the same paragraph.

Headers

ドキュメントは、ヘッダーを使用して異なるセクションに分割できます。ヘッダーは次の構文を使用します：

# Level One
## Level Two
### Level Three
#### Level Four
##### Level Five
###### Level Six

ヘッダー行は段落と同様に、任意のインライン構文を含むことができます。

Tip

ドキュメント内であまり多くのレベルのヘッダーを使用しないようにしましょう。過度にネストされたドキュメントは、再構成する必要があるか、別々のトピックをカバーするいくつかのページに分割する必要があることを示しているかもしれません。

Code blocks

ソースコードは、以下の例に示すように、4つのスペースまたは1つのタブのインデントを使用してリテラルブロックとして表示できます。

This is a paragraph.

    function func(x)
        # ...
    end

Another paragraph.

さらに、コードブロックは三重のバックティックで囲むことができ、オプションで「言語」を指定してコードブロックのハイライト方法を指定できます。

A code block without a "language":

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

and another one with the "language" specified as `julia`:

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

Note

「フェンス付き」コードブロックは、最後の例に示されているように、インデントされたコードブロックよりも好まれるべきです。なぜなら、インデントされたコードブロックがどの言語で書かれているかを指定する方法がないからです。

Block quotes

外部ソースからのテキスト、例えば書籍やウェブサイトからの引用は、次のように引用の各行の前に > 文字を付けて引用できます。

Here's a quote:

> 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.

Markdown.Paragraph(Any["注意：各行の ", Markdown.Code("", ">"), " 文字の後には単一のスペースが必要です。引用ブロック自体には、他のトップレベルまたはインライン要素が含まれる場合があります。"])

Images

画像の構文は、上記で述べたリンクの構文に似ています。リンクの前に ! 文字を付けることで、指定されたURLから画像を表示し、リンクではなくなります。

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

Lists

順不同リストは、リスト内の各項目の前に *、+、または - を付けることで作成できます。

A list of items:

  * item one
  * item two
  * item three

各 * の前に2つのスペース、後に1つのスペースがあることに注意してください。

リストには、リスト、コードブロック、または引用ブロックなどの他のネストされたトップレベル要素を含めることができます。リスト内にトップレベル要素を含める場合は、各リスト項目の間に空行を残す必要があります。

Another list:

  * item one

  * item two

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

  * And a sublist:

      + sub-item one
      + sub-item two

Note

リスト内の各項目の内容は、項目の最初の行に揃える必要があります。上記の例では、フェンシングコードブロックは item two の i に揃えるために4つのスペースでインデントされる必要があります。

順序付きリストは、"バレット"文字（*、+、または-）を正の整数とそれに続く.または)に置き換えることで書かれます。

Two ordered lists:

 1. item one
 2. item two
 3. item three

 5) item five
 6) item six
 7) item seven

順序付きリストは、上記の例の2番目のリストのように、1以外の数字から始めることができます。順序なしリストと同様に、順序付きリストにはネストされたトップレベル要素を含めることができます。

Display equations

大きな $\LaTeX$ 方程式は、段落内にインラインで収まらない場合、以下の例のように "language" math を使用したフェンシングコードブロックを使って表示方程式として書くことができます。

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

Footnotes

この構文は、Footnote referencesのインライン構文とペアになっています。そのセクションも必ずお読みください。

脚注テキストは、脚注参照構文に似た以下の構文を使用して定義されますが、脚注ラベルに追加される : 文字が異なります。

[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements
    indented by 4 spaces or one tab.

      * item one
      * item two
      * item three

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

Note

パース中に、すべての脚注参照が一致する脚注を持っていることを確認するためのチェックは行われません。

Horizontal rules

<hr> HTML タグの同等物は、3つのハイフン（---）を使用することで実現できます。例えば：

Text above the line.

---

And text below the line.

Tables

基本的なテーブルは、以下に示す構文を使用して記述できます。マークダウンテーブルには制限された機能があり、上記で説明した他の要素とは異なり、ネストされたトップレベル要素を含むことはできません – インライン要素のみが許可されています。テーブルには常に列名を含むヘッダー行が必要です。セルはテーブルの複数の行や列にまたがることはできません。

| Column One | Column Two | Column Three |
|:---------- | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |

Note

上記の例に示されているように、| 文字の各列は垂直に整列されている必要があります。

カラムのヘッダーセパレーターの両端に : 文字がある場合、その行は左揃え、右揃え、または（両端に : がある場合）中央揃えを指定します。 : 文字がない場合は、カラムは右揃えにデフォルト設定されます。

Admonitions

特別にフォーマットされたブロックは、注意喚起として知られ、特定の発言を強調するために使用できます。これらは次の !!! 構文を使用して定義できます：

!!! note

    This is the content of the note.
    It is indented by 4 spaces. A tab would work as well.

!!! warning "Beware!"

    And this is another one.

    This warning admonition has a custom title: `"Beware!"`.

!!!の後の最初の単語は、注意喚起のタイプを宣言します。特別なスタイリングを生成すべき標準的な注意喚起タイプがあります。すなわち（深刻度の降順で）：danger、warning、info/note、およびtipです。

独自の注意書きタイプを使用することもできますが、タイプ名は小文字のラテン文字（a-z）のみを含む必要があります。たとえば、次のような terminology ブロックを作成できます。

!!! terminology "julia vs Julia"

    Strictly speaking, "Julia" refers to the language,
    and "julia" to the standard implementation.

ただし、そのMarkdownの特定の注意書きタイプを特別扱いするコードがない限り、デフォルトのスタイルが適用されます。

ボックスのカスタムタイトルは、注意喚起のタイプの後に文字列（ダブルクォーテーションで囲まれた）として提供できます。注意喚起のタイプの後にタイトルテキストが指定されていない場合は、タイプ名がタイトルとして使用されます（例：note 注意喚起の場合は "Note"）。

注意事項は、他のほとんどのトップレベル要素と同様に、他のトップレベル要素（例：リスト、画像）を含むことができます。

Markdown String Literals

md"" マクロを使用すると、Markdown 文字列を直接 Julia コードに埋め込むことができます。このマクロは、Julia ソースファイル内に Markdown 形式のテキストを簡単に含めるために設計されています。

Usage

result = md"This is a **custom** Markdown string with [a link](http://example.com)."

JuliaのMarkdownは、基本的な文字列リテラルと非常に似た方法で補間をサポートしていますが、オブジェクト自体をMarkdownツリーに保存するという点が異なります（文字列に変換するのではなく）。Markdownコンテンツがレンダリングされると、通常のshowメソッドが呼び出され、これらは通常通りオーバーライドできます。この設計により、基本的な構文を煩雑にすることなく、参照のような任意に複雑な機能でMarkdownを拡張することが可能になります。

原則として、Markdownパーサー自体はパッケージによって任意に拡張することもできるし、まったくカスタムのMarkdownフレーバーを使用することもできるが、一般的にはそれは不要であるべきである。

API reference

Markdown.MD — Type

MD

MDはMarkdownドキュメントを表します。MDコンストラクタは通常直接使用すべきではなく、内部データ構造を構築するためです。代わりに、エクスポートされたマクロ@md_strおよび@doc_strを使用してMDオブジェクトを構築できます。

source

Markdown.@md_str — Macro

@md_str -> MD

与えられた文字列をMarkdownテキストとして解析し、対応するMDオブジェクトを返します。

例

julia> s = md"# こんにちは、世界！"
  こんにちは、世界！
  ≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD

source

Markdown.@doc_str — Macro

@doc_str -> MD

与えられた文字列をMarkdownテキストとして解析し、行およびモジュール情報を追加して、対応するMDオブジェクトを返します。

@doc_strはBase.Docsモジュールと併用できます。詳細については、ドキュメントに関するマニュアルセクションも参照してください。

例

julia> s = doc"f(x) = 2*x"
  f(x) = 2*x

julia> typeof(s)
Markdown.MD

source

Markdown.html — Function

html([io::IO], md)

Markdownオブジェクトmdの内容をHTML形式で出力します。オプションのioストリームに書き込むか、文字列を返します。

代わりにshow(io, "text/html", md)またはrepr("text/html", md)を使用することもできますが、これらは出力を<div class="markdown"> ... </div>要素でラップする点が異なります。

例

julia> html(md"hello _world_")
"<p>hello <em>world</em></p>\n"

source

Markdown.latex — Function

latex([io::IO], md)

Markdownオブジェクトmdの内容をLaTeX形式で出力します。オプションのioストリームに書き込むか、文字列を返します。

代わりにshow(io, "text/latex", md)またはrepr("text/latex", md)を使用することもできます。

例

julia> latex(md"hello _world_")
"hello \\emph{world}\n\n"

source