Markdown
Визуализация для отрисовки Markdown — упрощенного языка разметки.
Поддерживается язык разметки GitHub Flavored Markdown (GFM), за исключением вставок raw HTML , части плагинов и функциональности Yandex Flavored Markdown.
Для отрисовки чарта используется библиотека @diplodoc/transform. Подробнее см. документацию Diplodoc.
Доступные элементы разметки
Заголовки
Чтобы создать заголовок, используйте знак (#), например:
# Заголовок h1
## Заголовок h2
### Заголовок h3
#### Заголовок h4
Заголовок страницы оформляется h1-заголовком. Далее — разделы (h2) и подразделы по уровням вложенности. Нельзя пропускать вложенность заголовков.
Начертания
Чтобы задать для текста полужирное начертание, заключите его в двойные звездочки:
Этот текст **жирный**.
Чтобы задать для текста курсивное начертание, заключите его в знаки подчеркивания:
Этот текст _наклонный_.
Чтобы задать для текста полужирное и курсивное начертание, заключите его одновременно в двойные звездочки и знаки подчеркивания:
Этот текст _**жирный и наклонный**_.
Этот текст **_жирный и наклонный_**.
Чтобы сделать текст зачеркнутым, заключите его в две тильды (~~):
Этот текст ~~зачеркнутый~~.
Чтобы сделать текст подчеркнутым, заключите его в два плюса (++):
Этот текст ++подчеркнутый++.
Чтобы сделать текст в нижнем регистре, заключите его в знаки тильды (~):
Этот текст в ~нижнем~ регистре.
Чтобы сделать текст в верхнем регистре, заключите его в знаки (^):
Этот текст в ^верхнем^ регистре.
Чтобы сделать текст моноширинный, заключите его в знаки (##):
Этот текст ##моноширинный##.
Чтобы сделать выделенный текст, заключите его в два знака равно (==):
Этот текст ==выделенный==.
Цвет текста
Вы можете задать цвет текста с помощью форматирования: {цвет}(текст). Поддерживаются следующие значения цвета:
- gray — серый;
- yellow — желтый;
- orange — оранжевый;
- red — красный;
- green — зеленый;
- blue — синий;
- violet — фиолетовый.
Например, следующая разметка:
Этот текст {green}(зеленого) цвета.
будет отображаться так:
Этот текст зеленого цвета.
Списки
Неупорядоченный список
Неупорядоченный (маркированный) список можно отформатировать с помощью звездочек (*), дефисов (-) или знаков плюс (+). Например, следующая разметка Markdown:
- Элемент 1
- Элемент 2
- Элемент 3
будет отображаться как:
- Элемент 1
- Элемент 2
- Элемент 3
Чтобы вложить один список в другой, добавьте отступ для элементов дочернего списка. Разметка:
- Элемент 1
- Элемент A
- Элемент B
- Элемент 2
будет отображаться как:
- Элемент 1
- Элемент A
- Элемент B
- Элемент 2
Упорядоченный список
Упорядоченный (ступенчатый) список можно отформатировать с помощью соответствующих цифр. Разметка:
1. Первый пункт
1. Второй пункт
1. Третий пункт
будет отображаться как:
- Первый пункт
- Второй пункт
- Третий пункт
Чтобы вложить один список в другой, добавьте отступ для элементов дочернего списка. Например:
1. Первый пункт
1. Вложенный пункт
1. Вложенный пункт
1. Второй пункт
Таблицы
Таблицы не входят в основную спецификацию Markdown, но их поддерживает GFM. Создавать таблицы можно с помощью символов вертикальной черты | и дефиса -. Дефисы позволяют создавать для каждого столбца заголовок. Вертикальные черты разделяют столбцы. Чтобы таблица правильно отображалась, добавьте перед ней пустую строку.
Разметка:
Колонка по левому краю | Колонка по правому краю | Колонка по центру
:--- | ---: | :---:
Текст | Текст | Текст
будет отображаться как:
| Колонка по левому краю | Колонка по правому краю | Колонка по центру |
|---|---|---|
| Текст | Текст | Текст |
Если необходимо добавить в ячейку таблицы перенос строки или более сложный элемент (например, список или блок кода), воспользуйтесь альтернативной разметкой:
#|
|| **Заголовок1** | **Заголовок2** ||
|| Текст | Текст ||
|#
Пример разметки с переносами и списком:
#|
||Текст
на двух строчках
|
- Пункт 1
- Пункт 2
- Пункт 3
- Пункт 4||
|#
См. подробнее в документации YFM.
Каты
Используйте каты, чтобы скрыть часть контента, например дополнительную информацию или длинные блоки кода.
Разметка:
{% cut "Заголовок ката" %}
Контент, который отобразится по нажатию.
{% endcut %}
будет отображаться так:
Заголовок ката
Контент, который отобразится по нажатию.
Табы
Используйте табы для взаимоисключающих разделов. Например, чтобы разделить инструкции для разных ОС.
Разметка:
{% list tabs %}
- Название таба 1
Текст таба 1.
* Можно использовать списки.
* И **другую** разметку.
- Название таба 2
Текст таба 2.
{% endlist %}
будет отображаться так:
Текст таба 1.
- Можно использовать списки.
- И другую разметку.
Текст таба 2.
Чтобы элемент был раскрыт по умолчанию, добавьте к нему атрибут {selected}:
Разметка:
{% list tabs %}
- Название таба 1
Текст таба 1.
- Название таба 2 {selected}
Пункт будет открыт по умолчанию.
- Название таба 3
Текст таба 3.
{% endlist %}
будет отображаться так:
Текст таба 1.
Пункт будет открыт по умолчанию.
Текст таба 3.
Аккордеон
Аккордеон позволяет свернуть или раскрыть содержимое по вашему выбору и подходит для организации больших объемов информации.
Разметка:
{% list tabs accordion %}
- Название пункта 1
Контент для пункта 1.
- Название пункта 2
Контент для пункта 2.
- Название пункта 3
Контент для пункта 3.
{% endlist %}
будет отображаться так:
Контент для пункта 1.
Контент для пункта 2.
Контент для пункта 3.
Чтобы элемент был раскрыт по умолчанию, добавьте к нему атрибут {selected}.
Разметка:
{% list tabs accordion %}
- Название пункта 1
Контент для пункта 1.
- Название пункта 2 {selected}
Пункт будет открыт по умолчанию.
- Название пункта 3
Контент для пункта 3.
{% endlist %}
будет отображаться так:
Контент для пункта 1.
Пункт будет открыт по умолчанию.
Контент для пункта 3.
Ссылки
Синтаксис Markdown для встроенной ссылки состоит из [текста ссылки] и (URL-адреса)` :
[DataLens](https://datalens.ru)
Вставка кода
Markdown поддерживает как встраивание фрагментов кода в предложение, так и их размещение между предложениями в виде отдельных огражденных блоков.
const a = 10;
Такая вставка преобразуется в код с подсветкой.
const a = 10;
Код внутри строки <html class="ie no-js">.
Для вставки кода внутри предложений нужно заключать этот код в апострофы `<html class="ie no-js">`.
Перенос строки
Для переноса строки внутри абзаца нужно использовать два пробела ⋅⋅ в конце строки.
Всплывающие подсказки
Всплывающие подсказки позволяют при нажатии на термине отображать связанное с ним по ключу термина определение. Разметка:
[*term_key]: Определение термина, которое может включать в себя _базовую_ разметку:
* списки;
* ссылки;
* картинки и т.д.
Использование [термина](*term_key) в тексте.
будет отображаться так:
Использование [термина](*term_key) в тексте.
Примечание
На данный момент использование всплывающих подсказок в блоках кода возможно, только если у блока кода не указан язык.
Изображения
![alt text](https://yastatic.net/q/logoaas/v2/DataLens.svg "Текст для подсказки при ховере" =100x200)
Эмодзи
Чтобы добавить эмодзи, введите ключевое слово и добавьте с двух сторон двоеточие (:). Список доступных ключевых слов можно посмотреть в визуальном редакторе.
Например, следующая разметка:
Эмодзи :smiley:.
будет отображаться так:
Эмодзи 😀.
Диаграммы Mermaid
Mermaid — библиотека для создания диаграмм и блок-схем в браузере с помощью простого языка разметки. Она позволяет создавать диаграммы, используя синтаксис, похожий на Markdown.
Библиотека имеет множество встроенных шаблонов и функций для создания различных типов диаграмм, например: блок-схемы, графы, деревья, диаграммы Ганта, mind-карты, C4-диаграммы.
С помощью текстовых определений задается описание структуры, которое преобразуется в диаграмму. Разметка:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
будет отображаться как:
См. подробнее в документации Mermaid.
Примечание
При использовании Mermaid учитывайте следующие ограничения:
- отсутствует поддержка HTML;
- нельзя использовать атрибут
classдля стилизации диаграмм; - нельзя использовать CSS-переменные для цветов;
- Markdown внутри блоков диаграмм поддерживается частично, например не работают ссылки.