Списки определений
Списки определений - это расширенная функция Markdown, используемая для создания списков терминов с их соответствующими определениями, часто применяемая в глоссариях, объяснении терминов или описании параметров.
Базовый синтаксис
Базовый формат
Базовый формат списка определений состоит из термина и определения, где термин находится на отдельной строке, а определение начинается со следующей строки с двоеточия:
Термин
: Содержание определения
Результат отображения:
Термин : Содержание определения
Несколько терминов и определений
Markdown
: Легковесный язык разметки
: Создан Джоном Грубером в 2004 году
HTML
: Язык гипертекстовой разметки
: Стандартный язык разметки для создания веб-страниц
Результат отображения:
Markdown : Легковесный язык разметки : Создан Джоном Грубером в 2004 году
HTML : Язык гипертекстовой разметки : Стандартный язык разметки для создания веб-страниц
Расширенное использование
Многострочные определения
Содержание определения может включать несколько строк, последующие строки должны иметь отступ:
Термин
: Это первая строка определения
Это вторая строка, требующая отступа не менее одного пробела
Это новый абзац, требующий отступа не менее одного пробела и пустой строки перед ним
Результат отображения:
Термин : Это первая строка определения Это вторая строка, требующая отступа не менее одного пробела
Это новый абзац, требующий отступа не менее одного пробела и пустой строки перед ним
Использование других элементов Markdown в определениях
В содержании определения можно использовать другие элементы Markdown, такие как ссылки, выделение, код и т.д.:
Синтаксис Markdown
: **Markdown** поддерживает различные форматы текста:
- *Курсив* и **жирный**
- [Ссылка](https://www.markdownlang.com)
- `Встроенный код`
- > Блок цитаты
- Списки и другие элементы
Результат отображения:
Синтаксис Markdown : Markdown поддерживает различные форматы текста:
- Курсив и жирный
- Ссылка
Встроенный код
Блок цитаты
- Списки и другие элементы
Вложенные списки определений
В некоторых реализациях Markdown можно создавать вложенные списки определений:
Внешний термин
: Внешнее определение
Внутренний термин
: Внутреннее определение
: Еще одно внутреннее определение
Результат отображения (на поддерживающих платформах):
Внешний термин : Внешнее определение
Внутренний термин : Внутреннее определение : Еще одно внутреннее определение
Совместимость и различия реализаций
Поддержка на разных платформах
Платформа/Инструмент | Поддержка списков определений | Специальный синтаксис | Поддержка вложенности |
---|---|---|---|
GitHub Markdown | ❌ | - | - |
GitLab Markdown | ✅ | Стандартный | ✅ |
Jekyll (kramdown) | ✅ | Стандартный | ✅ |
Hugo | ✅ | Стандартный | ✅ |
CommonMark | ❌ | - | - |
VitePress | ✅ | Стандартный | ✅ |
Pandoc | ✅ | Стандартный | ✅ |
HTML-вывод
Большинство процессоров Markdown преобразуют списки определений в HTML-элементы <dl>
, <dt>
и <dd>
:
<dl>
<dt>Термин</dt>
<dd>Содержание определения</dd>
<dt>Другой термин</dt>
<dd>Другое определение</dd>
</dl>
Различные синтаксические варианты
Некоторые процессоры могут требовать различные синтаксические варианты:
<!-- Стандартный синтаксис -->
Термин
: Определение
<!-- Компактный синтаксис (для некоторых процессоров) -->
Термин: Определение
<!-- Синтаксис с дополнительным пробелом (для некоторых процессоров) -->
Термин
: Определение
Области применения
Глоссарий
Списки определений отлично подходят для создания глоссариев или словарей терминов:
## Глоссарий программирования
API
: Интерфейс программирования приложений, набор правил, позволяющих различным программным приложениям взаимодействовать.
Фреймворк
: Библиотека программного обеспечения, предоставляющая стандартизированную структуру для разработки приложений.
Git
: Распределенная система контроля версий для отслеживания изменений в процессе разработки проекта.
IDE
: Интегрированная среда разработки, программное приложение, содержащее редактор кода и различные инструменты разработки.
Результат отображения:
Глоссарий программирования
API : Интерфейс программирования приложений, набор правил, позволяющих различным программным приложениям взаимодействовать.
Фреймворк : Библиотека программного обеспечения, предоставляющая стандартизированную структуру для разработки приложений.
Git : Распределенная система контроля версий для отслеживания изменений в процессе разработки проекта.
IDE : Интегрированная среда разработки, программное приложение, содержащее редактор кода и различные инструменты разработки.
Документация API
Списки определений используются в документации API для объяснения параметров или опций:
## Параметры запроса
user_id
: **Обязательно** - Уникальный идентификатор пользователя.
: Тип: `integer`
name
: **Необязательно** - Отображаемое имя пользователя.
: Тип: `string`
: Значение по умолчанию: `null`
status
: **Необязательно** - Состояние пользователя.
: Тип: `string`
: Допустимые значения: `active`, `inactive`, `suspended`
: Значение по умолчанию: `active`
Результат отображения:
Параметры запроса
user_id : Обязательно - Уникальный идентификатор пользователя. : Тип: integer
name : Необязательно - Отображаемое имя пользователя. : Тип: string
: Значение по умолчанию: null
status : Необязательно - Состояние пользователя. : Тип: string
: Допустимые значения: active
, inactive
, suspended
: Значение по умолчанию: active
Описание конфигурации
Списки определений также подходят для объяснения параметров конфигурации:
## Параметры конфигурации
debug
: Включение или отключение режима отладки.
: Тип: `boolean`
: Значение по умолчанию: `false`
: Пример: `debug: true`
log_level
: Уровень детализации ведения журнала.
: Тип: `string`
: Допустимые значения: `error`, `warn`, `info`, `debug`
: Значение по умолчанию: `info`
: Пример: `log_level: debug`
max_connections
: Максимальное количество одновременных подключений.
: Тип: `integer`
: Значение по умолчанию: `100`
: Пример: `max_connections: 500`
Лучшие практики
Согласованность
✅ Рекомендуемые действия:
1. **Сохранять согласованный стиль между термином и определением**
- Термин использует лаконичные слова или фразы
- Определение в формат предложения, с заглавной буквы, с точкой в конце
- Для многострочных определений сохранять одинаковый отступ
2. **Разумно группировать**
- Связанные термины вместе
- Использовать заголовки для разделения разных списков определений
3. **Для технических терминов**
- Включать тип информации
- Добавлять примеры
- Отмечать обязательные или необязательные
❌ Избегайте:
1. Термин слишком длинный, превышающий одну строку
2. Термин с большим количеством форматированного текста
3. Отсутствие четкой категоризации
4. Определение, содержащее несвязанную информацию
Альтернативные решения
В платформах, не поддерживающих списки определений, можно имитировать другие форматы:
<!-- Использование полужирного шрифта и отступа -->
**Термин**
Содержание определения
**Другой термин**
Другое содержание определения
<!-- Использование таблиц -->
| Термин | Определение |
|------|------|
| API | Интерфейс программирования приложений |
| IDE | Интегрированная среда разработки |
<!-- Использование заголовков и абзацев -->
### Термин
Содержание определения
### Другой термин
Другое содержание определения
Примеры практического применения
Документация программного обеспечения
## Требования к системе
Операционная система
: **Windows**: Windows 10 или выше
: **macOS**: macOS 10.14 (Mojave) или выше
: **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+
Аппаратное обеспечение
: **Процессор**: 4-ядерный 2.0 ГГц или выше
: **Память**: Минимум 8GB RAM, рекомендуется 16GB
: **Хранилище**: Минимум 10GB свободного места, SSD-хранилище
Сеть
: Широкополосное интернет-соединение (минимум 10 Мбит/с)
: Разрешены исходящие подключения на следующие порты: 80, 443, 22
Научная документация
## Научные термины
Датасет
: Набор данных для анализа или оценки.
: В данном исследовании использовались образцы из публичного хранилища (n=1000).
Переменная
: **Эффект**: Входной фактор, который исследователь контролирует.
В данном исследовании эффект - это температура окружающей среды.
: **Результат**: Выходной фактор, измеряемый в исследовании.
В данном исследовании результат - это скорость обработки.
: **Контрольная переменная**: Фактор, который остается неизменным в эксперименте.
В данном исследовании включаются влажность и нагрузка на процессор.
Уровень значимости
: Вероятность, используемая для определения того, имеет ли результат значение для статистического анализа.
: В данном исследовании используется p < 0.05 в качестве стандарта значимости.
Решения для часто возникающих проблем
Списки определений не отображаются
Если ваши списки определений не отображаются правильно:
- Проверьте, поддерживает ли платформа синтаксис списков определений
- Убедитесь, что между термином и определением нет пустой строки
- Проверьте, есть ли подходящие пробелы перед двоеточием (некоторые процессоры могут иметь конкретные требования)
- Попробуйте увеличить отступ или изменить синтаксис варианта
Проблемы с вложенными списками
Вложенные списки определений могут иметь проблемы в некоторых процессорах:
- Увеличьте уровень отступа (например, внутренний термин использует 4 или 8 пробелов)
- Убедитесь, что между слоями есть подходящие пустые строки
- Если проблема продолжается, рассмотрите использование других структур (например, обычные списки)
Формат проблем
Если формат в определении неверен:
- Проверьте, сохраняется ли правильный отступ для всех абзацев и элементов
- Убедитесь, что блочные элементы (например, блоки кода, списки) имеют правильные разделители пустых строк в определении
- Попробуйте увеличить отступ
Связанные синтаксисы
- Списки - Базовый синтаксис списков
- Таблицы - Структурированное представление данных
- Блоки кода - Синтаксис блоков кода
Инструменты и плагины
- markdown-it-deflist: Добавляет поддержку списков определений для markdown-it
- kramdown: Встроенный парсер Markdown, поддерживающий списки определений
- remark-definition-list: Плагин определения списков для парсера remark
Списки определений - это мощная расширенная функция Markdown, особенно хорошо подходит для создания объяснений терминов, параметров и конфигурации. Хотя этот синтаксис не поддерживается всеми процессорами Markdown, на поддерживаемых платформах он обеспечивает четкую, структурированную форму для технической документации, делая сложные сведения более понятными и доступными для справки.