- Заголовки
- Начертания
- Списки
- Таблицы
- Ссылки
- Вставка кода
- Изображения
- Заметки
- Переиспользование контента
- Табы
- Каты
- Видео
- Переменные
- Метаданные
Чтобы создать заголовок, используйте символ (#), например:
# Заголовок h1
## Заголовок h2
### Заголовок h3
#### Заголовок h4В YFM используется 4 уровня заголовков. Заголовок страницы должен быть первого уровня. Для заголовков подразделов можно использовать второй, третий и четвертый уровни.
Важно! Нельзя пропускать вложенность заголовков.
Чтобы на заголовки документа можно было сослаться, во время сборки для каждого заголовка формируется якорь. По умолчанию якорь — это текст заголовка, записанный в латинской транслитерации. Такой якорь изменится, если вы измените текст заголовка.
Чтобы якорь не изменялся, укажите его в явном виде после заголовка. Вы можете указать несколько якорей одновременно:
## Заголовок h2 {#custom} {#header} {#custom-header}Чтобы задать для текста полужирное начертание, заключите его в двойные звездочки (*):
Этот текст выделен **полужирным шрифтом**.Чтобы задать для текста курсивное начертание, заключите его в знаки подчеркивания:
Этот текст выделен _курсивом_.Чтобы задать для текста полужирное и курсивное начертание, заключите его одновременно в двойные звездочки и знаки подчеркивания:
Этот текст _**жирный и наклонный**_.
Этот текст **_жирный и наклонный_**.Чтобы ввести символы в верхнем индексе, их нужно обернуть в ^:
Этот текст в ^верхнем индексе^.Чтобы оформить неупорядоченный маркированный список, используйте символы *, - или +. Рекомендуемый символ — *.
Например, разметка:
* Элемент 1
* Элемент 2
* Элемент 3будет отображаться как:
- Элемент 1
- Элемент 2
- Элемент 3
Чтобы оформить вложенный маркированный список, добавьте отступ для элементов дочернего списка. Допустимый размер отступа — от двух до пяти пробелов. Рекомендуемый размер отступа — четыре пробела.
Например, разметка:
* Элемент 1
* Элемент A
* Элемент B
* Элемент 2будет отображаться как:
- Элемент 1
- Элемент A
- Элемент B
- Элемент 2
Чтобы оформить упорядоченный нумерованый список, используйте цифры с символом . или ). Рекомендованный формат разметки: цифра 1 и символ ..
Например, разметка:
1. Первый пункт
1. Второй пункт
1. Третий пункт
будет отображаться как:
- Первый пункт
- Второй пункт
- Третий пункт
Чтобы оформить вложенный упорядоченный список, добавьте отступ для элементов дочернего списка. Допустимый размер отступа — от двух до пяти пробелов. Рекомендуемый размер отступа — четыре пробела.
Например, разметка:
1. Первый пункт
1. Вложенный пункт
1. Вложенный пункт
1. Второй пункт
будет отображаться как:
- Первый пункт
- Вложенный пункт
- Вложенный пункт
- Второй пункт
Таблицы состоят из одной строки с заголовками, разделительной строки и строк с данными.
Каждая строка таблицы состоит из ячеек, отделенных друг от друга символами |.
В ячейках разделительной строки используются только символы - и :. Символ : ставится в начале, в конце или с обеих сторон содержимого ячейки разделительной строки, чтобы обозначить выравнивание текста в соответствующем столбце по левой стороне, по правкой стороне или по центру.
Таблицу нужно отделять от предшествующего и последующего текста пустыми строками.
Например, разметка:
Колонка по левому краю | Колонка по правому краю | Колонка по центру
:--- | ---: | :---:
Текст | Текст | Текстбудет отображаться как:
| Колонка по левому краю | Колонка по правому краю | Колонка по центру |
|---|---|---|
| Текст | Текст | Текст |
Ссылки имеют вид [текст](ссылка), где:
[текст]— текст ссылки.(ссылка)— URL или путь до файла, на который делается ссылка.
Например, разметка:
[ссылка на README.md](README.md)будет отображаться так:
В YFM вы можете добавлять ссылки на другие md-файлы без указания текста ссылки. Он подставится автоматически из заголовка указанного файла.
Например, ссылка:
[{#T}](README.md)будет отображаться так:
Вы можете встроить фрагмент кода в текст абзаца или вынести его в отдельный блок.
Чтобы вставить фрагмент кода в текст, используйте символ `.
Например, разметка:
Предложение с `фрагментом кода`.будет отображаться так:
Предложение с фрагментом кода.
Чтобы оформить фрагмент кода как отдельный блок, используйте утроенный символ `. Для подсветки синтаксиса укажите язык, на котором написан код.
Например, разметка:
```js
let a= 10;
```
будет отобраться как фрагмент кода с подсветкой:
let a= 10;Чтобы вставить изображение в документ, воспользуйтесь разметкой вида
![alt text](_assets/image.png "Текст подсказки" =100x200)Здесь:
-
[alt text]— альтернативный текст изображения; -
_assets/image.png— путь до файла изображения;Важно! изображения должны храниться в каталоге, имя которого начинается с символа
_, иначе они будут удалены при сборке. -
"Текст подсказки"— текст подсказки при наведении указателя на изображение; -
=100x200— размер изображения в пикселях.
Вы можете один раз объявить изображение в тексте документа, а затем вызывать его в тексте с помощью короткой сслки. Для этого:
-
Объявите изображение:
[image]: _assets/image.png "Текст подсказки"
-
Вставьте изображение с помощью разметки:
![alt text][image]
Такой способ может быть удобен, когда нужно вставить одно изображение несколько раз.
Заметка — это визуально выделенный блок, который позволяет привлечь внимание к определенному содержимому.
Существует 4 типа заметок: примечание (info), совет (tip), важно (warning) и внимание (alert).
Не следует часто использовать блоки заметок, так как они могут отвлекать пользователя от основного содержимого. Также, хотя эти элементы могут содержать YFM, лучше не перегружать их, делая простыми и понятными.
{% note info %}
Это примечание.
{% endnote %}{% note tip %}
Это совет.
{% endnote %}{% note warning %}
Это важная информация.
{% endnote %}{% note alert %}
Это предупреждение.
{% endnote %}По умолчанию заметки имеют стандартный заголовок, но его можно переопределить:
{% note info "Custom title" %}
Это важная информация.
{% endnote %}Если в кавычках ничего не указывать, у заметки не будет никакого заголовка:
{% note info "" %}
Это важная информация.
{% endnote %}Вы можете вынести повторяющийся контент в отдельный файл и вставлять его в документ с помощью элемента {% include %}. Часто такой подход оказывается удобнне, чем "копировать-вставить".
Чтобы использовать один и тот же контент в нескольких местах:
-
Сохраните такой текст в отдельном md-файле.
Важно! Такие файлы должны храниться в каталоге, имя которого начинается с символа
_, например_includes. Если этого не сделать, файлы будут удалены при сборке. -
Вставьте в документ ссылку на файл:
{% include notitle [Описание](_includes/file.md) %}Здесь:
notitle— если параметр указан, заголовок файла будет не будет вставлен в текст.[Описание]— описание файла. Не влияет на сборку, нужно только для удобства рефакторинга документа.(_includes/file.md)— путь до файла.
В результате при сборке контент файла будет вставлен в документ. Если в файле есть относительные ссылки на другие документы или изображения, они будут перестроены.
Вы можете оформить текст в виде вкладок. Это может быть полезно, например, чтобы разделить схожий контент и не перегружать страницу текстом.
Чтобы создать вкладки, используйте разметку вида:
{% list tabs %}
- Название таба1
Контент таба1.
* Можно использовать списки.
* И **другую** разметку.
- Название таба2
Контент таба2.
{% endlist %}Важно! При использовании вкладок обязательно оставлять пустые строки:
- Перед и после строк
{% list tabs %}и{% endlist %}. - Между текстом одной вкладки и заголовком следующей вкладки.
Внутри вкладок можно использовать YFM-разметку: списки, таблицы, изображения, код и т.д.
Каты позволяют сворачивать контент ("убирать под кат"). Это можно использовать в длинных листингах, примерах кода и тд. Внутри катов можно использовать YFM.
Чтобы создать кат, используйте разметку вида:
{% cut "Заголовок ката" %}
Контент который мы хотим скрыть
{% endcut %}Вы можете вставлять в страницу видео с наиболее популярных платформ:
@[youtube](dQw4w9WgXcQ)
@[vimeo](19706846)
@[vine](etVpwB7uHlw)
@[prezi](1kkxdtlp4241)
Больше подробностей на странице плагина.
В YFM вы можете объявлять и использовать переменные. При сборке переменные будут подставлены в текст документации или использованы для вычисления условий. Это удобно, например, для сборки документации разных версий сервиса из одних и тех же исходных файлов.
Чтобы объявить и использовать переменные в документе:
-
Создайте в корневом каталоге документа файл
presets.yaml. -
Объявите переменные в файле
presets.yamlв формате:default: variable-name-1: значение переменной 1 variable-name-2: значение переменной 2 -
Чтобы вставить значение переменной в документ как текст, используйте разметку:
Какой-то текст {{ variable-name-1 }} продолжение текста. -
Чтобы оставить значение в документе как текст, используйте разметку:
Какой-то текст not_var{{ variable-name-1 }} продолжение текста.
Вы можете включать в сборку документа тот или иной фрагмент текста в зависимости от значений переменных.
Например, чтобы собрать две версии документа для разных ОС используйте разметку вида:
{% if OS == 'iOS' %}
Скачайте приложение в [App Store](https://www.apple.com/ios/app-store/).
{% else %}
Скачайте приложение в [Google Play](https://play.google.com).
{% endif %}
Важно! Перед и после оператора фильтра обязательно ставить пробел
Переменные в presets.yaml для примеров ниже:
default:
user:
name: Alice
users:
- Alice
- Mark
Hello {{ user.name | capitalize }}! => Hello Alice!
{{ users | length }} => 2
{{ user.name | length }} | length => 5
Переменные в presets.yaml для примеров ниже:
default:
users:
- Alice
- Mark
Prefix {% for user in users %} {{user}} {% endfor %} Postfix
Prefix Alice Mark Postfix
Prefix
{% for user in users %}
{{user}}
{% endfor %}
Postfix
Prefix
Alice
Mark
Postfix
Prefix {% for user1 in users %} {% for user2 in users %} {{user1}}+{{user2}} {% endfor %} {% endfor %} Postfix
Prefix Alice+Alice Alice+Mark Mark+Alice Mark+Mark Postfix
Переменные в presets.yaml для примеров ниже:
default:
user:
name: Pasha
Hello M{{ user.name.slice(1) }}! => Hello Masha!
Hello M{{ user.name.slice(1, 2) }}sha! => Hello Masha!
В начале файла можно добавить метаданные в формате yaml.
---
title: Заголовок
description: Описание
---