Модуль 02 — Списки, ссылки и изображения

Перечисления, инструкции по шагам, чек-листы и связи между документами

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

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

01

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

Исходник
Что понадобится:

- PostgreSQL 17
- VS Code
- учебная база

Порядок установки:

1. Скачать дистрибутив
1. Запустить установщик
1. Проверить версию
Результат

Что понадобится:

  • PostgreSQL 17
  • VS Code
  • учебная база

Порядок установки:

  1. Скачать дистрибутив
  2. Запустить установщик
  3. Проверить версию

Правила

  • Маркер пункта — -, * или + и пробел. Смена маркера посреди списка начинает новый список
  • Нумерация берётся из первого пункта, остальные номера программа расставит сама. Поэтому 1. у всех пунктов — законный приём: вставка шага в середину не требует перенумерации
  • Список начинается с числа первого пункта: 3. даст список, который начинается с трёх
  • Пустая строка перед списком обязательна по смыслу: без неё часть программ приклеит список к абзацу
02

Вложенные списки и содержимое пункта

Вложенный пункт сдвигается вправо так, чтобы его маркер стоял под текстом родительского пункта. Для - это 2 пробела, для 1. — 3 пробела. Так же сдвигается всё, что должно остаться внутри пункта: второй абзац, код, цитата.

Исходник
1. Подготовьте сервер
   - обновите пакеты
   - откройте порт 5432

   Второй абзац того же пункта.

2. Установите СУБД
   ```bash
   sudo apt install postgresql-17
   ```
Результат

  1. Подготовьте сервер

    • обновите пакеты
    • откройте порт 5432

    Второй абзац того же пункта.

  2. Установите СУБД

    sudo apt install postgresql-17
Недостаточный отступ — самая частая ошибка в инструкциях: код или второй абзац «выпадают» из пункта, нумерация после них начинается заново с единицы. Если после блока кода список снова пошёл с «1.», проверьте отступ.
03

Списки задач (GFM)

Исходник
## Готовность к релизу

- [x] Тесты проходят
- [x] Документация обновлена
- [ ] Запись в CHANGELOG
- [ ] Согласование с заказчиком
Результат

Готовность к релизу

  • ☑ Тесты проходят
  • ☑ Документация обновлена
  • ☐ Запись в CHANGELOG
  • ☐ Согласование с заказчиком

Квадратные скобки с пробелом — невыполненная задача, с x — выполненная. На git-хостингах флажки в описании задачи или запроса на слияние обычно можно отмечать мышью, а платформа показывает прогресс «2 из 4».

04

Ссылки

Исходник
Документация: [PostgreSQL](https://www.postgresql.org/docs/ "Официальная").

Автоссылка: <https://nevabit.ru>

Подробнее в [установке](docs/install.md)
и в разделе [Требования](#требования).

Ссылка-сноска на [спецификацию][cm].

[cm]: https://spec.commonmark.org/
Результат

Документация: PostgreSQL.

Автоссылка: https://nevabit.ru

Подробнее в установке и в разделе Требования.

Ссылка-сноска на спецификацию.

Виды ссылок

  • [текст](адрес "подсказка") — встроенная ссылка; подсказка необязательна
  • <https://...> — адрес сам становится ссылкой. GFM распознаёт и голые адреса с https:// и www., но угловые скобки работают везде
  • [текст][метка] и строка [метка]: адрес в любом месте документа — удобно, когда одна ссылка повторяется или адрес длинный
  • docs/install.md — относительный путь к файлу в том же репозитории: работает и на хостинге, и в редакторе, не ломается при переименовании проекта
  • #требования — якорь на заголовок. Правило построения якоря задаёт платформа: обычно строчные буквы, пробелы заменены на дефисы, знаки препинания удалены. Проверяйте ссылку щелчком в предпросмотре
Текст ссылки должен говорить, куда она ведёт. «Инструкция по установке» вместо «здесь» и «по ссылке» — так документ читается и при быстром просмотре, и программами экранного доступа.
05

Изображения

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

![Схема базы: users, posts, likes](docs/img/schema.png "Учебная база")

[![Логотип проекта](docs/img/logo.png)](https://nevabit.ru)

Практика использования

  • Изображения храните в репозитории, например в docs/img/, и подключайте относительным путём. Картинка по внешнему адресу однажды пропадёт
  • Альтернативный текст описывает смысл картинки, а не повторяет имя файла: не «screenshot1», а «Окно pgAdmin с подключением к серверу»
  • Размер изображения Markdown не задаёт. Если нужно, используют HTML: <img src="docs/img/schema.png" alt="Схема" width="400"> — большинство платформ это разрешают
  • Изображение внутри ссылки (второй пример) — кликабельная картинка

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

  • Вложенный элемент сдвигается до начала текста родительского пункта
  • 1. у всех пунктов — нормальный способ вести нумерацию
  • Ссылки внутри проекта — относительными путями, на разделы — через якорь
  • У изображения всегда осмысленный альтернативный текст
  • Списки задач — расширение GFM, на других платформах могут выглядеть как обычный текст
Практические задания — на учебном портале. Задания, критерии оценивания, сдача работ и оценки преподавателя — в курсе на portal.nevabit.ru. Учётную запись выдаёт преподаватель.
Модуль 01: Текст Все модули Модуль 03: Код и таблицы