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.

Как и в случае с литералами в предыдущем разделе, если необходимо записать литеральные обратные апострофы внутри двойных обратных апострофов, используйте четное число больше двух. Обратите внимание, что если необходимо включить в разметку \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.

Заголовки

С помощью заголовков документ можно разделить на различные разделы. Для заголовков используется следующий синтаксис:

# Уровень один
## Уровень два
### Уровень три
#### Уровень четыре
##### Уровень пять
###### Уровень шесть

Строка заголовка может содержать любой встроенный синтаксис так же, как и абзац.

Старайтесь не использовать слишком много уровней заголовков в одном документе. Документ с высоким уровнем вложенности может свидетельствовать о необходимости его реструктуризации или разбиения на несколько страниц, посвященных отдельным темам.

Блоки кода

Исходный код может быть отображен в виде буквенного блока с отступом в четыре пробела, как показано в следующем примере.

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

Содержимое каждого элемента списка должно выравниваться в соответствии с первой строкой элемента. В приведенном выше примере огражденный блок кода должен быть указан с отступом в четыре пробела, чтобы быть выровненным по i в 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
    ```

При анализе не проверяется наличие совпадающих сносок у всех ссылок на сноски.

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

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

Как показано в приведенном выше примере, каждый столбец символов | должен быть выровнен по вертикали.

Символ `:` на любом конце разделителя заголовка столбца (строки, содержащей символы `-`) определяет, является ли эта строка выровненной по левому краю, по правому краю или (если `:` появляется на обоих концах) по центру. При отсутствии символов `:` по умолчанию столбец будет выровнен по правому краю.

Замечания (Admonitions)

Для выделения конкретных примечаний можно использовать специально отформатированные блоки, называемые замечаниями (admonitions). Они могут быть определены с помощью следующего синтаксиса !!!:

!!! 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, но в целом в этом нет необходимости.