Markdown

Этот раздел описывает синтаксис Markdown Julia, который поддерживается стандартной библиотекой Markdown. Поддерживаются следующие элементы Markdown:

Inline elements

Здесь "встраиваемые" элементы относятся к элементам, которые можно найти внутри блоков текста, т.е. абзацев. К ним относятся следующие элементы.

Bold

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

A paragraph containing a **bold** word.

Italics

Окружите слова одной звездочкой, *, чтобы отобразить заключенный текст курсивом.

A paragraph containing an *italicized* word.

Literals

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

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

Links

Ссылки на внешние или внутренние цели можно писать, используя следующий синтаксис, где текст, заключенный в квадратные скобки, [ ], является названием ссылки, а текст, заключенный в круглые скобки, ( ), является 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. Хорошо включать перекрестные ссылки на изменяющие/неизменяющие версии функции или подчеркивать разницу между двумя похожими функциями.

Footnote references

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

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

Toplevel elements

Следующие элементы могут быть записаны либо на "верхнем уровне" документа, либо внутри другого элемента "верхнего уровня".

Paragraphs

Параграф — это блок обычного текста, возможно содержащий любое количество встроенных элементов, определенных в разделе Inline elements выше, с одной или несколькими пустыми строками выше и ниже него.

This is a paragraph.

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

Headers

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

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

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

Code blocks

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

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

Block quotes

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

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.

Обратите внимание, что после символа > в каждой строке должен быть один пробел. Цитируемые блоки могут содержать другие элементы верхнего уровня или встроенные элементы.

Images

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

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

Lists

Ненумерованные списки можно написать, предварив каждый элемент в списке символами *, + или -.

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

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

Display equations

Большие $\LaTeX$ уравнения, которые не помещаются в строке внутри абзаца, могут быть написаны в виде отображаемых уравнений, используя заблокированный код с "языком" math, как в примере ниже.

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

Footnotes

Этот синтаксис сочетается с встроенным синтаксисом для Footnote references. Убедитесь, что вы также прочитали этот раздел.

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

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

Horizontal rules

Эквивалент тега HTML <hr> можно получить, используя три дефиса (---). Например:

Text above the line.

---

And text below the line.

Tables

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

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

Admonitions

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

!!! note

    This is the content of the note.
    It is indented by 4 spaces. A tab would work as well.

!!! 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).

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

Markdown String Literals

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

Usage

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

Markdown Syntax Extensions

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

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

API reference

MD

@md_str -> MD

julia> s = md"# Привет, мир!"
  Привет, мир!
  ≡≡≡≡≡≡≡≡≡≡≡≡≡

julia> typeof(s)
Markdown.MD

@doc_str -> MD

julia> s = doc"f(x) = 2*x"
  f(x) = 2*x

julia> typeof(s)
Markdown.MD

html([io::IO], md)

julia> html(md"hello _world_")
"<p>hello <em>world</em></p>\n"

latex([io::IO], md)

julia> latex(md"hello _world_")
"hello \\emph{world}\n\n"