Markdown

В этом разделе описывается синтаксис разметки Markdown в Julia, который поддерживается стандартной библиотекой 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.

@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. Хорошо включать перекрестные ссылки на изменяющие/не изменяющие версии функции или выделять разницу между двумя похожими функциями.

Ссылки на сноски

Можно писать именованные и нумерованные ссылки на сноски с использованием следующего синтаксиса. Имя сноски должно быть единственным буквенно-цифровым словом без знаков препинания.

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

Нумерованные списки создаются путем замены символа "пули", *, +, или -, положительным целым числом, за которым следует . или ).

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

Горизонтальные линии

Эквивалент тега <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

Markdown в Julia поддерживает интерполяцию очень похожим образом на обычные строковые литералы, с той разницей, что он будет хранить сам объект в дереве Markdown (в отличие от преобразования его в строку). При рендеринге содержимого Markdown будут вызываться обычные show методы, и их можно переопределять как обычно. Эта конструкция позволяет расширять Markdown произвольно сложными функциями (такими как ссылки) без усложнения основного синтаксиса.

В принципе, сам парсер Markdown также может быть произвольно расширен пакетами, или может использоваться полностью пользовательская разновидность Markdown, но это обычно не требуется.