Markdown

本節說明 Julia 的 markdown 語法，由 Markdown 標準函式庫啟用。支援下列 Markdown 元素

內嵌元素

此處的「內嵌」是指可以在文字區塊（例如段落）中找到的元素。這些元素包括下列元素。

粗體

用兩個星號 ** 包圍文字，以粗體顯示所包含的文字。

A paragraph containing a **bold** word.

斜體字

用一個星號 * 包圍文字，以斜體顯示所包含的文字。

A paragraph containing an *italicized* word.

文字

用單引號 ` 包圍應按原樣顯示的文字。

A paragraph containing a `literal` word.

在撰寫提及變數、函式或 Julia 程式其他部分的名稱的文字時，應使用文字。

提示

若要在文字中包含反引號字元，請使用三個反引號而不是一個反引號來包圍文字。

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

此外，任何奇數個反引號都可以用來包圍較少數量的反引號。

$\LaTeX$

用兩個反引號 `` 包圍應使用 $\LaTeX$ 語法顯示為數學式的文字。

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

提示

與前一節的文字相同，如果文字反引號需要寫在雙反引號內，請使用大於 2 的偶數。請注意，如果需要在 $\LaTeX$ 標記中包含單一文字反引號，則兩個包圍反引號就足夠了。

注意

如果文字嵌入在 Julia 原始碼中，則應適當轉譯 \ 字元，例如 "``\\LaTeX`` syntax in a docstring."，因為它會被解釋為字串文字。或者，為了避免轉譯，可以使用 raw 字串巨集和 @doc 巨集

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

連結

連結到外部或內部目標可以使用以下語法撰寫，其中方括號內 [ ] 的文字是連結名稱，括號內 ( ) 的文字是 URL。

A paragraph containing a link to [Julia](http://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 文件。最好包含至函數的變異/非變異版本的交叉參照，或強調兩個看似相似的函數之間的差異。

注意

上述交叉參照不是 Markdown 功能，而是依賴於 Documenter.jl，用於建置 Julia 基礎文件的。

腳註參照

命名和編號的腳註參照可以使用以下語法撰寫。腳註名稱必須是單一英數字詞彙，不包含標點符號。

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

注意

與腳註參照在同一個頁面中的任何地方都可以撰寫與腳註相關的文字。定義腳註文字所使用的語法會在下面的腳註區段中討論。

頂層元素

下列元素可以寫在文件「頂層」或其他「頂層」元素內。

段落

段落是純文字區塊，可能包含任何數量的內嵌元素，這些元素定義在上述的內嵌元素區段，上面和下面各有一行或多行空白。

This is a paragraph.

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

標題

文件可以使用標題分成不同的區段。標題使用下列語法

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

標題列可以包含任何內嵌語法，就像段落一樣。

提示

請盡量避免在單一文件中使用太多層級的標題。層層嵌套的文件可能表示需要重新調整結構，或將其分成數個頁面，涵蓋不同的主題。

程式碼區塊

原始碼可以使用四個空格的縮排顯示為文字區塊，如下列範例所示。

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

注意

如最後一個範例所示，「圍欄」程式碼區塊應優先於縮排程式碼區塊，因為沒有辦法指定縮排程式碼區塊是用哪種語言寫的。

區塊引文

來自外部來源的文字，例如書籍或網站的引文，可以使用>字元置於引文每一行的開頭，如下所示。

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.

請注意，每一行中的 > 字元後必須出現一個空格。引述區塊本身可能包含其他頂層或內嵌元素。

影像

影像的語法類似於上述連結語法。在連結前加上 ! 字元會顯示指定網址的影像，而不是連結到該影像。

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

清單

未排序清單可以透過在清單中的每個項目前面加上 *、+ 或 - 來撰寫。

A list of items:

  * item one
  * item two
  * item three

請注意每個 * 前面有兩個空格，每個 * 後面有一個空格。

清單可以包含其他巢狀頂層元素，例如清單、程式碼區塊或引述區塊。在清單中包含任何頂層元素時，每個清單項目之間應該留一行空白。

Another list:

  * item one

  * item two

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

  * And a sublist:

      + sub-item one
      + sub-item two

注意

清單中每個項目的內容必須與該項目的第一行對齊。在上述範例中，圍欄式程式碼區塊必須縮排四個空格，才能與 item two 中的 i 對齊。

排序清單是透過將「項目符號」字元（*、+ 或 -）替換為正整數，後接 . 或 ) 來撰寫。

Two ordered lists:

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

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

排序清單可以從一以外的數字開始，就像上述範例的第二個清單，它從五開始編號。與未排序清單一樣，排序清單可以包含巢狀頂層元素。

顯示方程式

無法在段落內嵌入的大型 $\LaTeX$ 方程式，可以使用包含「語言」math 的圍欄式程式碼區塊，來撰寫成顯示方程式，如下面的範例所示。

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

腳註

此語法與腳註參考的內嵌語法配對。請務必也閱讀該章節。

腳註文字使用下列語法定義，類似於腳註參考語法，除了在腳註標籤後方附加 : 字元。

[^1]: Numbered footnote text.

[^note]:

    Named footnote text containing several toplevel elements.

      * item one
      * item two
      * item three

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

注意

在分析處理期間，不會檢查所有腳註參考是否都有對應的腳註。

水平規則

可以使用三個連字號 (---) 來達成等同於 HTML 標籤 <hr> 的效果。例如

Text above the line.

---

And text below the line.

表格

可以使用下列所述的語法撰寫基本表格。請注意，Markdown 表格的功能有限，且無法包含巢狀頂層元素，這與上述其他元素不同，只允許內嵌元素。表格必須始終包含包含欄位名稱的標題列。儲存格無法跨越表格的多列或多行。

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

注意

如上述範例所示，每個 | 字元的欄位都必須垂直對齊。

在欄位標題分隔線 (包含 - 字元的列) 兩端的 : 字元，會指定該列是靠左、靠右或置中對齊 (當 : 出現在兩端時)。如果沒有提供 : 字元，則欄位會預設靠右對齊。

警告

稱為警示的特別格式區塊可被用來強調特定備註。它們可以使用下列 !!! 語法定義

!!! note

    This is the content of the note.

!!! 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 語法擴充

Julia 的 markdown 支援內插，方式與基本字串文字非常類似，不同之處在於它會將物件本身儲存在 Markdown 樹中（相對於將它轉換為字串）。當 Markdown 內容被渲染時，將會呼叫一般的 show 方法，而這些方法可以像往常一樣被覆寫。此設計允許 Markdown 被擴充為任意複雜的功能（例如參照），而不會弄亂基本語法。

原則上，Markdown 解析器本身也可以被套件任意擴充，或可以使用完全自訂的 Markdown 風格，但這通常是不必要的。