В этой главе описаны примеры форматирования текста для Markdown компонента.

 

 

Поддерживаемый стандарт и расширения

Базовый синтаксис - полная официальная спецификация CommonMark 0.31.2. Кратко о поддерживаемом форматировании; расширения поверх CommonMark включены по умолчанию. Название каждого пункта - ссылка на официальное описание синтаксиса.

•Форматирование кода - строчный код `code`, блок в ограждении из ``` (можно указать язык) и блок с отступом в 4 пробела.
•GitHub Flavored Markdown (GFM) - таблицы, пункты списка задач, зачеркивание, автоссылки.
•Сноски - ссылки вида [^id] с определением далее по тексту.
•Списки определений - термин и определение с отступом под ним.
•Выделение маркером, верхний и нижний индекс - ==текст==, x^2^, H~2~O.
•SmartyPants - типографские кавычки, тире и многоточие.
•Врезки в стиле Obsidian - > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION].

 

Ниже каждый пункт разобран подробно с примерами.

 

 

Что дает CommonMark

•Заголовки - # H1 / ## H2 / ### H3 / #### H4 / ##### H5 / ###### H6.
•Setext-заголовки - строка текста, а под ней === (уровень 1) или --- (уровень 2).
•Абзацы - разделяются пустой строкой. Принудительный перенос строки: два пробела в конце или \.
•Выделение - *italic* → курсив, **bold** → полужирный, ***both*** → и то и другое.
•Форматирование кода - строчный код `code` → code; блок в ограждении из ``` или ~~~ (указанный язык сохраняется как текст); блок с отступом - каждая строка начинается с 4 пробелов или табуляции.
•Маркированный список - - item, * item или + item; вложенность задается отступом.
•Нумерованный список - 1. item, 2. item …; номера могут идти не по порядку.
•Ссылки - [text](https://example.com) → text, с необязательным "title".
•Ссылки по идентификатору - [text][id] в тексте и [id]: https://example.com отдельной строкой.
•Изображения - ![alt](https://example.com/pic.png) на отдельной строке.
•Цитаты - > quoted line; вложенность - >> deeper.
•Тематический разделитель - ---, *** или ___ на отдельной строке.
•HTML-сущности - © → ©, — → -, & → &.
•Необрабатываемый HTML - блоки и строчные теги HTML выводятся как есть моноширинным шрифтом; разметка HTML не интерпретируется.
•Экранирование обратной косой чертой - \*, \#, \_ … для вывода знаков препинания буквально.

 

 

CommonMark - блок кода в ограждении

Ограждайте блок тремя обратными кавычками (или тремя тильдами). Пример:

 

 

```csharp

public override string ToString()

{

return "hello";

}

```

 

 

 

public override string ToString()

{

return "hello";

}

 

 

 

Расширения GFM

Помимо CommonMark компонент включает расширения GitHub Flavored Markdown (GFM):

•Таблицы - ячейки через вертикальную черту, заголовок отделяется |---|---|.
•Пункты списка задач - - [x] done, - [ ] todo.
•Зачеркивание - ~~text~~ → text.
•Автоссылки - обычные адреса https://... становятся кликабельными, работает и <https://...>.

 

 

GFM - таблицы

Ячейки разделяются вертикальной чертой. Строка заголовка обязательна и отделяется от тела строкой из дефисов. Завершающие вертикальные черты необязательны. Маркеры выравнивания в строке-разделителе (:---, :--:, ---:) распознаются, но в текущей версии на вывод не влияют - содержимое ячеек выравнивается по левому краю. Пример:

 

 

| Column A | Column B | Column C |

|----------|----------|----------|

| A1       | B1       | C1       |

| A2       | B2       | C2       |

 

 

Column A

Column B

Column C

A1

B1

C1

A2

B2

C2

 

 

GFM - список задач

Пункт списка, начинающийся с [ ] или [x] отображается с флажком. Пример:

 

 

- [x] Done

- [ ] To do

- [ ] Also to do

 

 

☑ Done

☐ To do

☐ Also to do

 

 

Дополнительные расширения

Помимо CommonMark и GFM по умолчанию включены следующие расширения:

•Сноски - text[^1] с определением [^1]: definition далее по тексту.
•Списки определений - термин, затем : definition с отступом под ним.
•Подсветка - ==marker== → маркер.
•Верхний индекс - x^2^ или x^(2) → x2.
•Нижний индекс - H~2~O → H2O.
•SmartyPants - "text" → “text”, -- → –, --- → -, ... → ….
•Врезки в стиле Obsidian - > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], > [!CAUTION].

 

 

Расширение - врезки в стиле Obsidian

Цитата, начинающаяся с [!TYPE] отображается как цветной блок соответствующего типа. Пять типов и их вид:

 

 

> [!NOTE] Side information you don't want to miss.

> [!TIP] Pro tip - make your reports better.

> [!IMPORTANT] Important context the reader has to know.

> [!WARNING] Something that needs the reader's attention.

> [!CAUTION] Risk of negative consequences.

 

 

 

 

NOTE

Side information you don't want to miss.

 

 

 

 

TIP

Pro tip - make your reports better.

 

 

 

 

IMPORTANT

Important context the reader has to know.

 

 

 

 

WARNING

Something that needs the reader's attention.

 

 

 

 

CAUTION

Risk of negative consequences.

 

 

 

Расширение - сноски

Вставьте [^id] в любом месте текста, чтобы добавить ссылку, затем определите ее далее с помощью [^id]: text. Идентификатором может быть любое слово. Пример:

 

 

Here is a footnote reference[^1] and another[^longnote].

 

[^1]: First footnote.

[^longnote]: Second footnote with more detail.

 

 

 

Here is a footnote reference[1] and another[2].

Сами сноски собираются внизу компонента под горизонтальным разделителем:

___________________________________

[1] First footnote.

[2] Second footnote with more detail.

 

 

Расширение - список определений

Разместите термин на отдельной строке, затем сделайте отступ у определения с помощью : и пробелов. Записи разделяются пустой строкой. Пример:

 

 

Term

:  Definition of the term.

 

Another term

:  Definition of the other term.

 

 

 

В отчете само двоеточие не выводится: термин отображается полужирным, определение - с отступом под ним, а записи разделяются пустой строкой.

 

 

Term

Definition of the term.

 

Another term

Definition of the other term.

 

 

 

Советы

•Редактор и просмотр прокручиваются синхронно - щелкните в любой из панелей для перехода.
•Перетаскивайте центральный разделитель, чтобы изменить размеры редактора и просмотра.
•Используйте панель инструментов сверху для быстрого форматирования.
•Нажмите Ctrl+F, чтобы открыть диалог поиска и замены.
•Выберите тему в списке справа вверху, чтобы изменить оформление просмотра.