Skip to content

markdown-and-extensions.md

Latest commit

 

History

History
394 lines (256 loc) · 15.8 KB

markdown-and-extensions.md

File metadata and controls

394 lines (256 loc) · 15.8 KB

Синтаксис Markdown разметки в документации Яндекс.Облака

Документация Яндекс.Облака разработана с использованием GitHub Flavored Markdown(GFM) с некоторыми расширениями.

Содержание

Базовые возможности Markdown

Заголовки

Для обозначения заголовка используется символ #. Пример синтаксиса:

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня

Базовые возможности GFM

Заголовки

Для обозначения заголовка используется символ #.

Пример синтаксиса:

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня

В документации Яндекс.Облака используется 4 уровня заголовков. Первый заголовок на странице — 1 уровня. Для заголовков подразделов можно использовать 2, 3 и 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.1. Вложенный пункт
    1.2. Вложенный пункт

  2. Второй пункт

Таблицы

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

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

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

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

Например, следующая разметка:

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

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

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

Ссылки

Ссылка состоит из двух частей:

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

Например, следующая разметка:

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

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

ссылка на README.md

В документации Яндекс.Облака вместо текста ссылки можно использовать расширение #T — указатель на заголовок файла, на который делается ссылка. Указатель на заголовок обрабатывается при сборке документации для отображения на сайте и текст соответствующего заголовка подставляется на место текста ссылки.

Например, следующая разметка

[{#T}](README.md)

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

Документация Яндекс.Облака

Оформление кода

Фрагмент кода можно оформить как часть предложения или как отдельный блок.

Фрагмент кода как часть предложения

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

Например, следующая разметка:

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

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

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

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

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

Например, следующая разметка:

    ```js
    let = 10;
    ```

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

let = 10;

Изображения

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

![alt text](_assets/image.png "Поясняющий текст при наведении указателя")

В документации Яндекс.Облака все изображения хранятся в папках с именем _assets:

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

Расширения для Markdown

Примечания

В документации Яндекс.Облака используются следующие типы примечаний:

  • Примечание: 
    {% note info %}

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

{% endnote %}
  • Предупреждение 
    {% note alert %}

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

{% endnote %}
  • Совет 
    {% note tip %}

Это совет.

{% endnote %}
  • Важная информация 
    {% note important %}

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

{% endnote %}

Перед текстом примечания и после него обязательно оставлять пустую строку.

Использование одинакового текста в разных файлах

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

  • Сохранить такой текст в отдельном файле в папке ru/_includes или en/_includes.
  • Добавить ссылку на файл с текстом в нужном месте документа с помощью расширения include:
    • Если нужно использовать все содержимое файла: 
      {% include [Описание](_includes/file.md) %}
    • Если нужно использовать содержимое файла без первого заголовка: 
      {% include notitle [Описание](_includes/file.md) %}
      В описании нужно вставить короткий комментарий про содержимое файла, на который указывает ссылка.

Ссылка на файл обрабатывается при сборке документации для отображения на сайте и вместо ссылки подставляется содержимое файла.

Вкладки

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

{% list tabs %}

- Заголовок вкладки 1

  Первая строка текста во вкладке 1.

  Вторая строка текста во вкладке 1.

- Заголовок вкладки 2

  Текст во вкладке 2.

{% endlist %}

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

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

Оглавление документа

Для каждого документа необходимо создать файл toc.yaml:

  • Только файлы, указанные в toc.yaml, обрабатываются при сборке документации и отображаются на сайте Яндекс.Облака.
  • Навигация по документу на сайте Яндекс.Облака генерируется на базе toc.yaml.

Файл toc.yaml имеет следующую структуру:

- title: Имя сервиса или документа
  href: index.yaml
  items:
    - name: Имя блока
      items:
        - name: Имя раздела
          href: path/to/file.md
        - name: Имя вложенного блока
          items:
            - name: Имя раздела во вложенном блоке
              href: path/to/some/file.md
    - name: Имя другого раздела
      href: path/to/another/file.md

В документации Яндекс.Облака можно использовать до 3 уровней вложенности в toc.yaml.

Переменные

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

{{ compute-full-name }} — это сервис для управления виртуальными машинами.

После сборки текст будет выглядеть так:

Yandex Compute Cloud — это сервис для управления виртуальными машинами.