Skip to content

Latest commit

 

History

History
427 lines (285 loc) · 18.6 KB

markdown-and-extensions.md

File metadata and controls

427 lines (285 loc) · 18.6 KB
Raw

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

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

Содержание

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

Заголовки

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

# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня
- [Оформление кода](#code)
    - [Фрагмент кода как часть предложения](#inline-code)
    - [Фрагмент кода отдельным блоком](#codeblock)
- [Изображения](#images)

Базовые возможности 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

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

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

[[!TITLE]](README.md)

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

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

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

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

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

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

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

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

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

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

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

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

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

    ```js
    let = 10;
    ```

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

let = 10;

Изображения

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

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

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

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

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

Примечания

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

  • Примечание: 
    > [!NOTE]
>
> Это примечание.
  • Предупреждение 
    > [!WARNING]
>
> Это предупреждение.
  • Совет 
    > [!TIP]
>
> Это совет.
  • Важная информация 
    > [!IMPORTANT]
>
> Это важная информация.

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

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

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

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

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

Вкладки

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

---

**[!TAB Заголовок вкладки 1]**

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

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

**[!TAB Заголовок вкладки 2]**

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

---

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

  • Перед и после строк вида ---.
  • Между текстом одной вкладки и заголовком следующей вкладки.

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

Для каждого документа необходимо создать файл 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.

Ключи (текстовые переменные)

Ключ позволяет задать значение переменной в файле keys.yaml и вставить ссылку на ключ в нужном месте документа с помощью расширения !KEYREF. Ссылка на ключ обрабатывается при сборке документации для отображения на сайте и вместо ссылки подставляется значение ключа. Если изменить значение переменной в файле keys.yaml, оно изменится во всем документе при следующей сборке.

Ключи можно использовать для имен сервисов или ролей, адресов хостов, текущего года.

Файл с ключами

Файл keys.yaml имеет следующий вид:

iam-full-name: Yandex Identity and Access Management
resmgr-full-name: Yandex Resource Manager
compute-full-name: Yandex Compute Cloud

Значение ключа не может содержать переносов строк.

Файл keys.yaml можно разместить:

  • В папках ru или en, если значение ключа будет одинаковым во всех документах.
  • В папке документа, если значение ключа будет отличаться в соответствующем документе.

Если один и тот же ключ указан в файле ru/keys.yaml и в файле ru/{document-name}/keys.yaml, при сборке документа document-name будет использовано значение ключа из файла в папке самого документа.

Использование ключей в тексте

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

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

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

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