Skip to content

Списки определений

Списки определений - это расширенная функция Markdown, используемая для создания списков терминов с их соответствующими определениями, часто применяемая в глоссариях, объяснении терминов или описании параметров.

Базовый синтаксис

Базовый формат

Базовый формат списка определений состоит из термина и определения, где термин находится на отдельной строке, а определение начинается со следующей строки с двоеточия:

markdown
Термин
: Содержание определения

Результат отображения:

Термин : Содержание определения

Несколько терминов и определений

markdown
Markdown
: Легковесный язык разметки
: Создан Джоном Грубером в 2004 году

HTML
: Язык гипертекстовой разметки
: Стандартный язык разметки для создания веб-страниц

Результат отображения:

Markdown : Легковесный язык разметки : Создан Джоном Грубером в 2004 году

HTML : Язык гипертекстовой разметки : Стандартный язык разметки для создания веб-страниц

Расширенное использование

Многострочные определения

Содержание определения может включать несколько строк, последующие строки должны иметь отступ:

markdown
Термин
: Это первая строка определения
  Это вторая строка, требующая отступа не менее одного пробела
  
  Это новый абзац, требующий отступа не менее одного пробела и пустой строки перед ним

Результат отображения:

Термин : Это первая строка определения Это вторая строка, требующая отступа не менее одного пробела

Это новый абзац, требующий отступа не менее одного пробела и пустой строки перед ним

Использование других элементов Markdown в определениях

В содержании определения можно использовать другие элементы Markdown, такие как ссылки, выделение, код и т.д.:

markdown
Синтаксис Markdown
: **Markdown** поддерживает различные форматы текста:
  - *Курсив* и **жирный**
  - [Ссылка](https://www.markdownlang.com)
  - `Встроенный код`
  - > Блок цитаты
  - Списки и другие элементы

Результат отображения:

Синтаксис Markdown : Markdown поддерживает различные форматы текста:

  • Курсив и жирный
  • Ссылка
  • Встроенный код
  • Блок цитаты

  • Списки и другие элементы

Вложенные списки определений

В некоторых реализациях Markdown можно создавать вложенные списки определений:

markdown
Внешний термин
: Внешнее определение

  Внутренний термин
  : Внутреннее определение
  : Еще одно внутреннее определение

Результат отображения (на поддерживающих платформах):

Внешний термин : Внешнее определение

Внутренний термин : Внутреннее определение : Еще одно внутреннее определение

Совместимость и различия реализаций

Поддержка на разных платформах

Платформа/ИнструментПоддержка списков определенийСпециальный синтаксисПоддержка вложенности
GitHub Markdown--
GitLab MarkdownСтандартный
Jekyll (kramdown)Стандартный
HugoСтандартный
CommonMark--
VitePressСтандартный
PandocСтандартный

HTML-вывод

Большинство процессоров Markdown преобразуют списки определений в HTML-элементы <dl>, <dt> и <dd>:

html
<dl>
  <dt>Термин</dt>
  <dd>Содержание определения</dd>
  
  <dt>Другой термин</dt>
  <dd>Другое определение</dd>
</dl>

Различные синтаксические варианты

Некоторые процессоры могут требовать различные синтаксические варианты:

markdown
<!-- Стандартный синтаксис -->
Термин
: Определение

<!-- Компактный синтаксис (для некоторых процессоров) -->
Термин: Определение

<!-- Синтаксис с дополнительным пробелом (для некоторых процессоров) -->
Термин
  : Определение

Области применения

Глоссарий

Списки определений отлично подходят для создания глоссариев или словарей терминов:

markdown
## Глоссарий программирования

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

Фреймворк
: Библиотека программного обеспечения, предоставляющая стандартизированную структуру для разработки приложений.

Git
: Распределенная система контроля версий для отслеживания изменений в процессе разработки проекта.

IDE
: Интегрированная среда разработки, программное приложение, содержащее редактор кода и различные инструменты разработки.

Результат отображения:

Глоссарий программирования

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

Фреймворк : Библиотека программного обеспечения, предоставляющая стандартизированную структуру для разработки приложений.

Git : Распределенная система контроля версий для отслеживания изменений в процессе разработки проекта.

IDE : Интегрированная среда разработки, программное приложение, содержащее редактор кода и различные инструменты разработки.

Документация API

Списки определений используются в документации API для объяснения параметров или опций:

markdown
## Параметры запроса

user_id
: **Обязательно** - Уникальный идентификатор пользователя.
: Тип: `integer`

name
: **Необязательно** - Отображаемое имя пользователя.
: Тип: `string`
: Значение по умолчанию: `null`

status
: **Необязательно** - Состояние пользователя.
: Тип: `string`
: Допустимые значения: `active`, `inactive`, `suspended`
: Значение по умолчанию: `active`

Результат отображения:

Параметры запроса

user_id : Обязательно - Уникальный идентификатор пользователя. : Тип: integer

name : Необязательно - Отображаемое имя пользователя. : Тип: string : Значение по умолчанию: null

status : Необязательно - Состояние пользователя. : Тип: string : Допустимые значения: active, inactive, suspended : Значение по умолчанию: active

Описание конфигурации

Списки определений также подходят для объяснения параметров конфигурации:

markdown
## Параметры конфигурации

debug
: Включение или отключение режима отладки.
: Тип: `boolean`
: Значение по умолчанию: `false`
: Пример: `debug: true`

log_level
: Уровень детализации ведения журнала.
: Тип: `string`
: Допустимые значения: `error`, `warn`, `info`, `debug`
: Значение по умолчанию: `info`
: Пример: `log_level: debug`

max_connections
: Максимальное количество одновременных подключений.
: Тип: `integer`
: Значение по умолчанию: `100`
: Пример: `max_connections: 500`

Лучшие практики

Согласованность

markdown
✅ Рекомендуемые действия:

1. **Сохранять согласованный стиль между термином и определением**
   - Термин использует лаконичные слова или фразы
   - Определение в формат предложения, с заглавной буквы, с точкой в конце
   - Для многострочных определений сохранять одинаковый отступ

2. **Разумно группировать**
   - Связанные термины вместе
   - Использовать заголовки для разделения разных списков определений

3. **Для технических терминов**
   - Включать тип информации
   - Добавлять примеры
   - Отмечать обязательные или необязательные

❌ Избегайте:

1. Термин слишком длинный, превышающий одну строку
2. Термин с большим количеством форматированного текста
3. Отсутствие четкой категоризации
4. Определение, содержащее несвязанную информацию

Альтернативные решения

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

markdown
<!-- Использование полужирного шрифта и отступа -->
**Термин**
   Содержание определения

**Другой термин**
   Другое содержание определения

<!-- Использование таблиц -->
| Термин | Определение |
|------|------|
| API | Интерфейс программирования приложений |
| IDE | Интегрированная среда разработки |

<!-- Использование заголовков и абзацев -->
### Термин
Содержание определения

### Другой термин
Другое содержание определения

Примеры практического применения

Документация программного обеспечения

markdown
## Требования к системе

Операционная система
: **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

Научная документация

markdown
## Научные термины

Датасет
: Набор данных для анализа или оценки.
: В данном исследовании использовались образцы из публичного хранилища (n=1000).

Переменная
: **Эффект**: Входной фактор, который исследователь контролирует.
   В данном исследовании эффект - это температура окружающей среды.
  
: **Результат**: Выходной фактор, измеряемый в исследовании.
   В данном исследовании результат - это скорость обработки.
  
: **Контрольная переменная**: Фактор, который остается неизменным в эксперименте.
   В данном исследовании включаются влажность и нагрузка на процессор.

Уровень значимости
: Вероятность, используемая для определения того, имеет ли результат значение для статистического анализа.
: В данном исследовании используется p < 0.05 в качестве стандарта значимости.

Решения для часто возникающих проблем

Списки определений не отображаются

Если ваши списки определений не отображаются правильно:

  1. Проверьте, поддерживает ли платформа синтаксис списков определений
  2. Убедитесь, что между термином и определением нет пустой строки
  3. Проверьте, есть ли подходящие пробелы перед двоеточием (некоторые процессоры могут иметь конкретные требования)
  4. Попробуйте увеличить отступ или изменить синтаксис варианта

Проблемы с вложенными списками

Вложенные списки определений могут иметь проблемы в некоторых процессорах:

  1. Увеличьте уровень отступа (например, внутренний термин использует 4 или 8 пробелов)
  2. Убедитесь, что между слоями есть подходящие пустые строки
  3. Если проблема продолжается, рассмотрите использование других структур (например, обычные списки)

Формат проблем

Если формат в определении неверен:

  1. Проверьте, сохраняется ли правильный отступ для всех абзацев и элементов
  2. Убедитесь, что блочные элементы (например, блоки кода, списки) имеют правильные разделители пустых строк в определении
  3. Попробуйте увеличить отступ

Связанные синтаксисы

Инструменты и плагины

  • markdown-it-deflist: Добавляет поддержку списков определений для markdown-it
  • kramdown: Встроенный парсер Markdown, поддерживающий списки определений
  • remark-definition-list: Плагин определения списков для парсера remark

Списки определений - это мощная расширенная функция Markdown, особенно хорошо подходит для создания объяснений терминов, параметров и конфигурации. Хотя этот синтаксис не поддерживается всеми процессорами Markdown, на поддерживаемых платформах он обеспечивает четкую, структурированную форму для технической документации, делая сложные сведения более понятными и доступными для справки.

Build by www.markdownlang.com