0013 — Markdown
Самый популярный формат для написания текстов сейчас — Markdown. Тут будет не ещё один самоучитель, а описание некоторых неочевидных вещей.
Markdown позволяет использовать для отступов от 1 до 4 пробелов и даже табуляции. Я настоятельно рекомендую использовать 4 пробела. Если где-то в вёрстке ошибка, это сразу будет видно — неправильно оформленный кусок будет отформатирован как блок кода при сборке.
До и после списков и блоков кода обязательно нужно ставить одну пустую строку.
В конце файла должен быть переход на новую строку.
У примеров кода должен быть указан синтаксис.
Если нужно показать результаты работы команды, используйте синтаксис
text
, а неbash
. При использовании синтаксисаbash
некоторые части кода будут выделены как ключевые слова:Text
This value not acceptable in this position. Use value `1` for this parameter.
Bash
This value not acceptable in this position. Use value `1` for this parameter.
Не используйте
$
. Я не понимаю, зачем некоторые ставят этот знак в начале команд. Чтобы показать, что команду нужно выполнять без привилегий суперпользователя? А можно наоборот, использоватьsudo
, чтобы показать привилегии? Меня коробит от того, что я не могу просто скопировать фрагмент кода с помощью соответствующей кнопки — обязательно нужно править этот фрагмент, либо целиться с помощью мыши.Разбивайте длинные команды на части с помощью
\
и бэктиков `. Про бэктики узнал совсем недавно: оказывается, Bash игнорирует всё, что между ними, и это можно использовать, чтобы делить на части длинные команды. Как я потом узнал, разработчики PowerShell вовсе отказались от\
, и там знак перехода на новую строку как раз бэктик `.Используйте злые линтеры, например, markdownlint.
Выучите правила Markdown.