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

По расширении для заключения меньшего количества символов обратного апострофа можно использовать любое нечетное количество обратных апострофов.

Окружите текст, который должен отображаться как математический, с помощью синтаксиса с двойными обратными апострофами, ``.

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

Упомянутая выше перекрестная ссылка не является функцией 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

Упорядоченный список может начинаться с числа, отличного от единицы, как, например, во втором списке приведенного выше примера, где он нумеруется с пяти. Как и неупорядоченные списки, упорядоченные списки могут содержать вложенные элементы верхнего уровня.

Отображение уравнений

Уравнения большого размера, которые не помещаются в строку абзаца, могут быть записаны как уравнения, располагаемые на отдельной строке, с помощью огражденного блока кода с меткой языка 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
    indented by 4 spaces or one tab.

      * item one
      * item two
      * item three

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

No checks are done during parsing to make sure that all footnote references have matching footnotes.

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

The equivalent of an <hr> HTML tag can be achieved using three hyphens (---). For example:

Текст над линией.

---

И текст под линией.

Таблицы

Базовые таблицы можно записывать с использованием синтаксиса, описанного ниже. Обратите внимание, что таблицы Markdown имеют ограниченные возможности и не могут содержать вложенные элементы верхнего уровня, в отличие от других элементов, описанных выше — допускаются только встроенные элементы. Таблицы всегда должны содержать строку заголовка с именами столбцов. Ячейки не могут охватывать несколько строк или столбцов таблицы.

| Столбец один| Столбец два | Столбец три  |
|:----------- |------------ |:----------- :|
| Строка `1`  | Столбец `2` |              |
| *Строка* 2  | **Строка** 2| Столбец ``3``|

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

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

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

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

!!! note

    Это содержимое примечания.
    Оно указано с отступом в 4 пробела. Табуляция тоже будет работать.

!!! warning "Beware!"

    Это другое примечание.

    У этого предупреждения есть настраиваемый заголовок: `"Beware!"`.

Первое слово после !!! определяет тип предупреждения. Существуют стандартные типы предупреждений, которые должны отображаться с особым стилем. А именно (в порядке убывания серьезности): danger, warning, info/note и tip.

Вы также можете использовать свои собственные типы предупреждений, если название типа содержит только строчные латинские буквы (a-z). Например, у вас может быть блок terminology, как показано ниже:

!!! terminology "julia vs Julia"

    Строго говоря, Julia относится к языку, а julia — к стандартной реализации.

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

Пользовательский заголовок для блока может быть указан в виде строки (в двойных кавычках) после типа предупреждения. Если после типа предупреждения не указан текст заголовка, то в качестве заголовка будет использовано название типа (например, «Примечание» для предупреждения «note»).

Предупреждения, как и большинство других элементов верхнего уровня, могут содержать другие элементы верхнего уровня (например, списки, изображения).

Строковые литералы Markdown

Макрокоманда md«» позволяет вставлять строки Markdown непосредственно в код Julia. Эта макрокоманда предназначена для упрощения включения текста в формате Markdown в исходные файлы Julia.

Использование

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

Расширения синтаксиса Markdown

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

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

Справка по API

# Markdown.MD — Type

MD

MD представляет документ Markdown. Обратите внимание, что конструктор MD обычно не следует использовать напрямую, поскольку он создает внутренние структуры данных. Вместо этого вы можете создавать объекты MD, используя экспортированные макросы @md_str и @doc_str.

# Markdown.@md_str — Macro

@md_str -> MD

Анализирует заданную строку как текст Markdown и возвращает соответствующий объект MD.

Примеры

julia> s = md"# Hello, world!"
  Hello, world!
  ≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD

# 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

# 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"

# 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"