Skip to content

Latest commit

 

History

History
475 lines (303 loc) · 17.9 KB

DOCS.md

File metadata and controls

475 lines (303 loc) · 17.9 KB
Raw

Синтаксис Yandex Flavored Markdown (YFM)

Содержание

Заголовки

Чтобы создать заголовок, используйте символ (#), например:

# Заголовок h1
## Заголовок h2
### Заголовок h3
#### Заголовок h4

В YFM используется 4 уровня заголовков. Заголовок страницы должен быть первого уровня. Для заголовков подразделов можно использовать второй, третий и четвертый уровни.

Важно! Нельзя пропускать вложенность заголовков.

Начертания

Чтобы задать для текста полужирное начертание, заключите его в двойные звездочки (*):

Этот текст выделен **полужирным шрифтом**.

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

Этот текст выделен _курсивом_.

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

Этот текст _**жирный и наклонный**_.
Этот текст **_жирный и наклонный_**.

Чтобы ввести символы в верхнем индексе их нужно обернуть в ^:

Этот текст в ^верхнем индексе^.

Списки

Неупорядоченный список

Чтобы оформить неупорядоченный маркированный список, используйте символы *, - или +.

Например, разметка:

- Элемент 1
- Элемент 2
- Элемент 3

будет отображаться как:

  • Элемент 1
  • Элемент 2
  • Элемент 3

Чтобы оформить вложенный маркированный список, добавьте отступ для элементов дочернего списка. Допустимый размер отступа — от двух до пяти пробелов. Рекомендуемый размер отступа — три пробела.

Например, разметка:

- Элемент 1
   - Элемент A
   - Элемент B
- Элемент 2

будет отображаться как:

  • Элемент 1
    • Элемент A
    • Элемент B
  • Элемент 2

Упорядоченный список

Чтобы оформить упорядоченный нумерованый список, используйте цифры с символом . или ). Рекомендованный формат разметки: цифра 1 и символ ..

Например, разметка:

1. Первый пункт
1. Второй пункт
1. Третий пункт

будет отображаться как:

  1. Первый пункт
  2. Второй пункт
  3. Третий пункт

Чтобы оформить вложенный упорядоченный список, добавьте отступ для элементов дочернего списка. Допустимый размер отступа — от двух до пяти пробелов. Рекомендуемый размер отступа — три пробела.

Например, разметка:

1. Первый пункт
    1. Вложенный пункт
    1. Вложенный пункт
1. Второй пункт

будет отображаться как:

  1. Первый пункт
    1. Вложенный пункт
    2. Вложенный пункт
  2. Второй пункт

Таблицы

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

Каждая строка таблицы состоит из ячеек, отделенных друг от друга символами |.

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

Таблицу нужно отделять от предшествующего и последующего текста пустыми строками.

Например, разметка:

Колонка по левому краю | Колонка по правому краю | Колонка по центру
:--- | ---: | :---:
Текст | Текст | Текст

будет отображаться как:

Колонка по левому краю Колонка по правому краю Колонка по центру
Текст Текст Текст

Ссылки

Ссылки имеют вид [текст](ссылка), где:

  • [текст] — текст ссылки.
  • (ссылка) — URL или путь до файла, на который делается ссылка.

Например, разметка:

[ссылка на README.md](README.md)

будет отображаться так:

ссылка на README.md

Ссылки с автоматической подстановкой текста из заголовка

В YFM вы можете добавлять ссылки на другие md-файлы без указания текста ссылки. Он подставится автоматически из заголовка указанного файла.

Например, ссылка:

[{#T}](README.md)

будет отображаться так:

Yandex Flavored Markdown

Вставка кода

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

Фрагмент кода внутри текста

Чтобы вставить фрагмент кода в текст, используйте символ `.

Например, разметка:

Предложение с `фрагментом кода`.

будет отображаться так:

Предложение с фрагментом кода.

Фрагмент кода отдельным блоком

Чтобы оформить фрагмент кода как отдельный блок, используйте утроенный символ `. Для подсветки синтаксиса укажите язык, на котором написан код.

Например, разметка:

```js
let a= 10;
```

будет отобраться как фрагмент кода с подсветкой:

let a= 10;

Изображения

Прямая вставка

Чтобы вставить изображение в документ, воспользуйтесь разметкой вида

![alt text](_assets/image.png "Текст подсказки" =100x200)

Здесь:

  • [alt text] — альтернативный текст изображения;

  • _assets/image.png — путь до файла изображения;

    Важно! изображения должны храниться в каталоге, имя которого начинается с символа _, иначе они будут удалены при сборке.

  • "Текст подсказки" — текст подсказки при наведении указателя на изображение;

  • =100x200 — размер изображения в пикселях.

Вставка через ссылку

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

  1. Объявите изображение:

    [image]: _assets/image.png "Текст подсказки"

  2. Вставьте изображение с помощью разметки:

    ![alt text][image]

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

Заметки

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

Существует 4 типа заметок: примечание (info), совет (tip), важно (warning) и внимание (alert).

Не следует часто использовать блоки заметок, так как они могут отвлекать пользователя от основного содержимого. Также, хотя эти элементы могут содержать YFM, лучше не перегружать их, делая простыми и понятными.

Примечание 

{% note info %}

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

{% endnote %}

note-info

Совет 

{% note tip %}

Это совет.

{% endnote %}

note-tip

Важно 

{% note warning %}

Это важная информация.

{% endnote %}

note-warning

Внимание 

{% note alert %}

Это предупреждение.

{% endnote %}

note-alert

Свой заголовок

По умолчанию заметки имеют стандартный заголовок, но его можно переопределить:

{% note info "Custom title" %}

Это важная информация.

{% endnote %}

Если в кавычках ничего не указывать, у заметки не будет никакого заголовка:

{% note info "" %}

Это важная информация.

{% endnote %}

Переиспользование контента

Вы можете вынести повторяющийся контент в отдельный файл и вставлять его в документ с помощью элемента {% include %}. Часто такой подход оказывается удобнне, чем "копировать-вставить".

Чтобы использовать один и тот же контент в нескольких местах:

  1. Сохраните такой текст в отдельном md-файле.

    Важно! Такие файлы должны храниться в каталоге, имя которого начинается с символа _, например _includes. Если этого не сделать, файлы будут удалены при сборке.

  2. Вставьте в документ ссылку на файл:

    {% include notitle [Описание](_includes/file.md) %}

    Здесь:

    • notitle — если параметр указан, заголовок файла будет не будет вставлен в текст.
    • [Описание] — описание файла. Не влияет на сборку, нужно только для удобства рефакторинга документа.
    • (_includes/file.md) — путь до файла.

В результате при сборке контент файла будет вставлен в документ. Если в файле есть относительные ссылки на другие документы или изображения, они будут перестроены.

Вкладки

Вы можете оформить текст в виде вкладок. Это может быть полезно, например, чтобы разделить схожий контент и не перегружать страницу текстом:

tabs

Чтобы создать вкладки используйте разметку вида:

{% list tabs %}

- Название таба1

  Контент таба1.

  - Можно исполдьзовать списки.
  - И **другую** разметку.

- Название таба2

  Контент таба2.

{% endlist %}

Важно! При использовании вкладок обязательно оставлять пустые строки:

  • Перед и после строк {% list tabs %} и {% endlist %}.
  • Между текстом одной вкладки и заголовком следующей вкладки.

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

Каты

Каты позволяют сворачивать контент ("убирать под кат"). Это можно использовать в длинных листингах, примерах кода и тд. Внутри катов можно использовать YFM.

Чтобы создать кат используйте разметку вида:

{% cut "Заголовок ката" %}

Контент который мы хотим скрыть

{% endcut %}

Переменные

В YFM вы можете объявлять и использовать переменные. При сборке переменные будут подставлены в текст документации или использованы для вычисления условий. Это удобно, например, для сборки документации разных версий сервиса из одних и тех же исходных файлов.

Подстановки

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

  1. Создайте в корневом каталоге документа файл presets.yaml.

  2. Объявите переменные в файле presets.yaml в формате:

    default:
  variable-name-1: значение переменной 1
  variable-name-2: значение переменной 2

  3. Чтобы вставить значение переменной в документ как текст, используйте разметку:

    Какой-то текст {{ variable-name-1 }} продолжение текста.

Условные операторы

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

Например, чтобы собрать две версии документа для разных ОС используйте разметку вида:

{% if  OS == 'iOS' %}

Скачайте приложение в [App Store](https://www.apple.com/ios/app-store/).

{% else %}

Скачайте приложение в [Google Play](https://play.google.com).

{% endif %}

Доступны условные операторы if, else if, else и операторы сравнения: ==, !=, <, >, <=, >=.

Метаданные

В начале файла можно добавить метаданные в формате yaml.

---
title: Заголовок
description: Описание
---