Модуль 03 — Код, таблицы и расширения

Всё, что нужно технической документации: команды, конфиги, сравнения и схемы

Прогресс курса Модуль 3 из 5

Что вы освоите в этом модуле

01

Код в строке

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

Исходник
Запустите `psql -U postgres` и проверьте `SHOW max_connections;`.

Переменная `MAX_RETRY_COUNT` задаётся в `.env`.

Апостроф внутри кода: `` `a` ``
Результат

Запустите psql -U postgres и проверьте SHOW max_connections;.

Переменная MAX_RETRY_COUNT задаётся в .env.

Апостроф внутри кода: `a`

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

02

Блоки кода

Многострочный код окружают строками из трёх обратных апострофов (или трёх тильд). Сразу после открывающих апострофов пишут язык — по нему платформа включает подсветку.

```sql
SELECT name, city
FROM users
WHERE age > 25;
```

```bash
sudo systemctl restart postgresql
```

```json
{ "port": 5432, "ssl": true }
```

Правила

  • Язык указывайте всегда, даже для простого текста — text. Так читателю сразу ясно, что это, а линтер не выдаёт предупреждений
  • Частые названия: sql, bash, powershell, python, json, yaml, ini, diff
  • Если внутри блока нужно показать сами ``` (как на этой странице), внешний блок открывают четырьмя апострофами
  • Отступ в 4 пробела тоже делает блок кода — это старый способ без подсветки. Из-за него случайный отступ превращает абзац в код
  • Команды пишите без приглашения $: иначе при копировании оно попадёт в терминал
03

Таблицы (GFM)

Исходник
| Команда    | Назначение          | Пример    |
|:-----------|:-------------------:|----------:|
| `SELECT`   | выборка             | 12 мс     |
| `INSERT`   | добавление строк    | 3 мс      |
| `a \| b`   | черта в ячейке      | —         |
Результат
КомандаНазначениеПример
SELECTвыборка12 мс
INSERTдобавление строк3 мс
a | bчерта в ячейке

Правила

  • Первая строка — заголовки, вторая — разделитель из дефисов, дальше — данные
  • Двоеточие в разделителе задаёт выравнивание: :--- влево, :---: по центру, ---: вправо. Числа выравнивайте вправо
  • Выравнивать столбцы пробелами в исходнике не обязательно, но так таблицу проще читать и править
  • Вертикальная черта внутри ячейки экранируется: \|
  • Объединять ячейки и писать несколько абзацев в ячейке нельзя. Если таблица не помещается — это знак, что данные лучше подать списком или разбить на две таблицы
04

Сноски и HTML внутри Markdown

Исходник
Лимит соединений по умолчанию — 100[^1].

[^1]: Параметр `max_connections` в postgresql.conf.

Нажмите <kbd>Ctrl</kbd>+<kbd>C</kbd>.

<details>
<summary>Полный вывод команды</summary>

Длинный текст скрыт, пока его не раскроют.

</details>
Результат

Лимит соединений по умолчанию — 1001.

Нажмите Ctrl+C.

Полный вывод команды

Длинный текст скрыт, пока его не раскроют.


1. Параметр max_connections в postgresql.conf.

Что важно знать

  • Сноски не входят ни в CommonMark, ни в спецификацию GFM, но их поддерживают многие платформы и генераторы документации. Текст сносок собирается внизу документа
  • HTML внутри Markdown разрешён стандартом, но платформы вырезают опасные теги и атрибуты: скрипты, стили, обработчики событий. Безопасно работают details, summary, kbd, sup, sub, br, img
  • Внутри блока details пустые строки после summary и перед </details> обязательны — без них Markdown внутри не обработается
05

Диаграммы Mermaid

Mermaid — язык описания схем текстом. Блок кода с языком mermaid платформа рисует как диаграмму: схему процесса, последовательность вызовов, ER-диаграмму. Схема хранится в git и правится как текст.

```mermaid
flowchart LR
    A[Студент] -->|сдаёт работу| B(Портал)
    B --> C{Проверено?}
    C -->|да| D[Оценка в журнале]
    C -->|нет| E[На доработку]
    E --> A
```
Mermaid поддерживают не все платформы и не все редакторы: где-то нужен плагин, где-то блок останется просто кодом. Перед тем как делать схему частью документации, проверьте её в предпросмотре той платформы, где документ будет жить. В VS Code для предпросмотра Mermaid нужно расширение.

Запомните главное

  • У каждого блока кода — язык, у команд — никаких $
  • В таблице вторая строка обязательна, двоеточия задают выравнивание
  • Таблицы и списки задач — GFM; сноски и Mermaid — возможности платформ
  • HTML работает только в безопасном подмножестве
  • Переносимость проверяется предпросмотром целевой платформы, а не редактора
Практические задания — на учебном портале. Задания, критерии оценивания, сдача работ и оценки преподавателя — в курсе на portal.nevabit.ru. Учётную запись выдаёт преподаватель.
Модуль 02: Списки и ссылки Все модули Модуль 04: README и документация