Skip to content

Latest commit

 

History

History
340 lines (228 loc) · 9.66 KB

md-syntax.md

File metadata and controls

340 lines (228 loc) · 9.66 KB

Синтаксис Extended Markdown

Итоговое отображение элементов есть в статье О портале документации.

Заголовки

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

Параграфы

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

Текс станет легче восприниматься для чтения.

Разрыв строки

Текст первой строки.<br> Текст второй строки.

Результат:

Текст первой строки.
Текст второй строки.

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

Пример **жирного текста**.
Пример *курсивного текста*.
Пример ~~зачеркнутого текста~~.

Результат:

Пример жирного текста. Пример курсивного текста. Пример зачеркнутого текста.

Цитаты

> Цитируемый однострочный текст.

Результат:

Цитируемый однострочный текст.

Списки

Нумерованный список

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

или

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

Результат:

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

Вложенный нумерованный список:

1. Пункт первый.

    1. Подпункт первый.
    1. Подпункт второй.
    
1. Пункт второй.

Результат:

  1. Пункт первый

    1. Подпункт первый.
    2. Подпункт второй.

  2. Пункт второй.

Ненумерованный список

- Пункт первый.
- Пункт второй.
- Пункт третий.

Результат:

  • Пункт первый.
  • Пункт второй.
  • Пункт третий.

Вложенный ненумерованный список:

- Пункт первый

    - Подпункт первый.
    - Подпункт второй.
    
- Пункт второй.

Результат:

  • Пункт первый

    • Подпункт первый.
    • Подпункт второй.

  • Пункт второй.

Изображения

Отдельным блоком:

Текст после изображения.

![Альтернативный текст](./assets/vk_icon_full.png)

Результат:

Текст после изображения.

Альтернативный текст

Встроенное в строку:

Текст с inline-изображением ![Альтернативный текст](./assets/vk_icon_inline.png "inline")

Результат:

Текст с inline-изображением Альтернативный текст.

Ограничения на имена файлов

Имя файла с изображением и путь к нему не должны содержать:

  • пробелов,
  • букв любых алфавитов, кроме латинского.

Ссылки

Относительная внутренняя ссылка (для ссылок на страницы внутри документации):

[Видимый текст ссылки](/ru/in/start)

Внешняя ссылка:

[Видимый текст ссылки](https://github.com/vk-cs/docs-public)

Ссылка на файл (будет отмечена иконкой, клик по ссылке приведет к скачиванию):

[Скачать картинку](https://github.com/vk-cs/docs-public/guides/assets/vk_icon_inline.png "download")

Ограничения на URL-адреса

URL-адрес ссылки не должен содержать:

  • пробелов,
  • букв любых алфавитов, кроме латинского.

Сворачиваемые блоки (шорткаты)

<details>
    <summary>Короткое видимое описание</summary>
       
    Подробный длинный скрытый текст
    Подробный длинный скрытый текст
    Подробный длинный скрытый текст
    Подробный длинный скрытый текст

</details>

Результат:

Короткое видимое описание

Подробный длинный скрытый текст Подробный длинный скрытый текст Подробный длинный скрытый текст Подробный длинный скрытый текст

Блоки с кодом

Пример блока кода для языка JavaScript:

```js
console.log('Hello World');
```

Результат:

console.log('Hello World');

Полный список поддерживаемых языков размещен по ссылке.

Таблицы

Для таблицы не рекомендуется делать больше 4 колонок.

| Заголовок 1 | Заголовок 2    | Заголовок 3  | Заголовок 4            |
| :---        | :----:         | ---:         | ---                    |
| Текст слева | Текст в центре | Текст справа | Текст без выравнивания |
| Столбец 1   | Столбец 2      | Столбец 3    | Столбец 4              |

Результат:

Заголовок 1 Заголовок 2 Заголовок 3 Заголовок 4
Текст слева Текст в центре Текст справа Текст без выравнивания
Столбец 1 Столбец 2 Столбец 3 Столбец 4

Вкладки (табы)

<tabs>
<tablist>
<tab>Вкладка 1</tab>
<tab>Вкладка 2</tab>
</tablist>
<tabpanel>

Содержимое Вкладки 1. Можно добавить произвольный текст.

</tabpanel>
<tabpanel>

Содержимое Вкладки 2. Можно добавить произвольный текст.

</tabpanel>
</tabs>

Порядок содержимого вкладок <tabpanel> должен совпадать с порядком вкладок <tab>. Содержимое вкладок может включать markdown-разметку.

Инфоблоки

Поддерживаемые типы инфоблоков:

  • info — дополнительная информация, которая может быть полезна читателю. Если он ее упустит, ничего страшного не случится.
  • warn — важная информация, к которой необходимо привлечь внимание читателя. Желательно, чтобы такая вставка содержала не более двух тезисов, а лучше — один. Тезисы обязательно должны быть связаны общей темой.
  • err — критически важная информация, пропустив которую читатель рискует что-то сломать или потерять деньги. Такая вставка должна содержать всего один тезис, сформулированный кратко.
<info>
Инфоблок с серым цветом фона
</info>
<warn>
Инфоблок с желтым цветом фона
</warn>
<err>
Инфоблок с красным цветом фона
</err>

Генерация описания API из swagger-файла

Позволяет сгенерировать страницу документацию из swagger-файла. Чаще всего используется для описания методов API.

Входные данные — спецификация в формате JSON.

![{swagger}](./assets/registry.swagger.json)

Результат:

Альтернативный текст

Больше примеров можно найти в разделе с описанием API.

Символы, которые требуется экранировать

\	 backslash
`	 backtick (see also escaping backticks in code)
*	 asterisk
_	 underscore
{ }	 curly braces
[ ]	 brackets
< >	 angle brackets
( )	 parentheses
#	 pound sign
+	 plus sign
-	 minus sign (hyphen)
.	 dot
!	 exclamation mark
|	 pipe (see also escaping pipe in tables)

Другие элементы HTML

Возможно встраивать любую html-разметку, но это крайне не приветствуется.