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

Синтаксис списка задач в Markdown

Список задач — обычный список, пункты которого начинаются с маркера флажка. Он состоит из трёх частей:

1. Маркер списка

   Дефис, звёздочка или плюс и пробел после него: -. Подойдёт и нумерованный пункт вроде 1..

2. Флажок в квадратных скобках

   [ ] с одним пробелом внутри — пустой флажок. [x] — отмеченный; заглавная [X] тоже подходит. Больше ничего между скобками быть не должно.

3. Пробел и текст

   Без пробела после ] строка остаётся обычным текстом со скобками.

- [x] Draft the spec
- [x] Add the edge cases
- [ ] Get a review
- [ ] Hand it to the agent

Так это видит читатель:

• Набросать спецификацию
• Добавить пограничные случаи
• Получить ревью
• Передать агенту

Вложенные флажки

Сделайте отступ у задачи под другой задачей, и получится подзадача. В большинстве рендереров хватает двух пробелов, надёжнее всего четыре:

- [ ] Release 2.0
    - [x] Update the changelog
    - [ ] Tag the build
    - [ ] Announce it
- [ ] Plan 2.1

В одном списке можно смешивать задачи и обычные пункты, а абзац, код или цитату под задачей можно поместить, сдвинув их так, чтобы они совпали с текстом задачи. Родительский флажок сам не отмечается, когда готовы подзадачи: его отмечаете вы.

Где отображаются флажки Markdown

• GitHub показывает списки задач как флажки в Markdown-файлах, задачах (issues), pull request и комментариях. В issue или pull request флажок можно отметить прямо на странице, и GitHub сам изменит текст.
• Markdown-приложения, следующие GFM, тоже их показывают. В DotMD они выглядят как флажки в режиме чтения. Там они только для чтения: чтобы отметить флажок, измените в строке [ ] на [x].
• Минимальные парсеры, которые знают только исходный Markdown или CommonMark, показывают текст как есть, со скобками. Он всё равно читается как список дел, только без флажков.

Если вы пишете в DotMD Editor, то Enter в конце задачи начинает следующую с пустого - [ ], и можно продолжать набирать пункты.

Галочка в Markdown без списка задач

Когда галочка нужна в таблице или в предложении, а не в списке, наберите сам символ. Символы Unicode — это текст, поэтому они видны в любом Markdown-приложении:

GitHub также понимает шорткоды эмодзи, например :white_check_mark:. Это возможность GitHub: в другом приложении они могут отобразиться как обычный текст, поэтому, если файл будут читать где-то ещё, лучше использовать сам символ.

Списки задач в планах и спецификациях

Списки задач нужны не только для приложений с делами. План или спецификация в Markdown часто заканчивается списком того, что осталось сделать, и каждый шаг легко проверить на отдельной строке:

## Tasks
- [x] Add the settings screen
- [ ] Write the migration
- [ ] Update the tests
- [ ] Update the docs

Пусть каждая задача будет одним действием, которое можно завершить и проверить. Для каждой группы используйте заголовок, а подзадачи вкладывайте только тогда, когда они относятся к одной родительской.

Почему вместо флажков видны скобки

• Нет пробела после скобки: - [x]Done — не задача. Пишите - [x] Done.
• Пробелы внутри скобок: [ ] с двумя пробелами или [ x ] — обычный текст.
• Нет маркера списка: строка, которая начинается только с [ ], не пункт списка.
• Текст, который начинается со скобки. В документации GitHub советуют экранировать скобку: пишите - [ ] \(Optional) Test it.
• Рендерер не знает GFM. Тогда вы увидите скобки, что бы ни набрали.

Чтобы проверить, как выглядит план с задачами, откройте файл в DotMD, где чтение бесплатно. Спецификации и планы часто пишут списками задач, а флажки помогают быстро просмотреть длинный список.

Вопросы о флажках в Markdown

Другие вопросы