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.

提示

与上一节中的文字一样，如果需要在双反引号内编写文字反引号，请使用大于两个的偶数个反引号。请注意，如果需要在 $\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.

请注意，每一行上的 > 字符后必须有一个空格。引用的块本身可以包含其他顶层元素或内联元素。

图像

图像的语法类似于上面提到的链接语法。在链接前加上 ! 字符将从指定的 URL 显示图像，而不是链接到该图像。

![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

有序列表可以从除 1 以外的数字开始，如上面的示例中的第二个列表，它从 5 开始编号。与无序列表一样，有序列表可以包含嵌套的顶层元素。

显示公式

大型$\LaTeX$公式如果不能在段落中内联显示，可以使用带有“language”为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
    ```

注意

在解析过程中不会进行任何检查以确保所有脚注引用都有匹配的脚注。

水平线

<hr> HTML 标签的等效方法可以使用三个连字符 (---) 来实现。例如

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 风格，但这通常是不必要的。