0013 — Markdown

Самый популярный формат для написания текстов сейчас — Markdown. Тут будет не ещё один самоучитель, а описание некоторых неочевидных вещей.

  1. Markdown позволяет использовать для отступов от 1 до 4 пробелов и даже табуляции. Я настоятельно рекомендую использовать 4 пробела. Если где-то в вёрстке ошибка, это сразу будет видно — неправильно оформленный кусок будет отформатирован как блок кода при сборке.

  2. До и после списков и блоков кода обязательно нужно ставить одну пустую строку.

  3. В конце файла должен быть переход на новую строку.

  4. У примеров кода должен быть указан синтаксис.

  5. Если нужно показать результаты работы команды, используйте синтаксис 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.
    
  6. Не используйте $. Я не понимаю, зачем некоторые ставят этот знак в начале команд. Чтобы показать, что команду нужно выполнять без привилегий суперпользователя? А можно наоборот, использовать sudo, чтобы показать привилегии? Меня коробит от того, что я не могу просто скопировать фрагмент кода с помощью соответствующей кнопки — обязательно нужно править этот фрагмент, либо целиться с помощью мыши.

  7. Разбивайте длинные команды на части с помощью \ и бэктиков `. Про бэктики узнал совсем недавно: оказывается, Bash игнорирует всё, что между ними, и это можно использовать, чтобы делить на части длинные команды. Как я потом узнал, разработчики PowerShell вовсе отказались от \, и там знак перехода на новую строку как раз бэктик `.

  8. Используйте злые линтеры, например, markdownlint.

  9. Выучите правила Markdown.