Предпросмотр Markdown

О предпросмотре Markdown

Markdown — самый безболезненный способ писать документацию, руководства и README: обычный текст, легко править, легко вести в системе контроля версий. Загвоздка в том, что при письме не видно результата. Этот инструмент закрывает пробел: слева печатаете, справа видите.

Поддерживаемый синтаксис

• Заголовки: от одного до шести # в начале строки для H1–H6. Обратите внимание, что пробел после # обязателен.
• Выделение: *курсив*, **жирный**, ***жирный курсив***, ~~зачёркнутый~~.
• Списки: - или * начинает маркированный список, 1. — нумерованный; для вложенности отступ в четыре пробела или табуляция.
• Списки задач: - [ ] сделать и - [x] готово отображаются как флажки.
• Таблицы: ячейки разделяются вертикальными чертами, вторая строка через --- задаёт заголовок, двоеточия управляют выравниванием.
• Код: строчный код в обратных кавычках; многострочный код в трёх обратных кавычках, при желании с названием языка.
• Цитаты: ведущий >, могут быть вложенными.
• Ссылки и изображения: [текст](url) и ![alt](url).
• Горизонтальная линия: три или более -, * или _ в отдельной строке.

Как писать таблицу

Таблицы — та часть Markdown, в которой ошибаются чаще всего. Формат такой:

| Имя  | Отдел    | Сумма |
|:-----|:--------:|------:|
| Анна | Разработка | 1200 |
| Борис| Маркетинг  |  980 |

Три момента: нужны и строка заголовка, и строка-разделитель; двоеточия в разделителе управляют выравниванием (двоеточие слева — по левому краю, с двух сторон — по центру, справа — по правому); и лучше держать число черт в строках одинаковым — отрисовка выдержит несовпадение, но исходник читается легче, когда всё выровнено.

Метки языка у блоков кода

Название языка после трёх обратных кавычек (например, ```javascript) заставляет большинство редакторов применять подсветку синтаксиса. Этот инструмент даёт соответствующую стилевую подсказку по названию языка, сохраняя исходный текст, так что его можно скопировать куда угодно.

Учтите, что содержимое внутри блока кода не разбирается как Markdown, поэтому писать там # или звёздочки безопасно — они не станут заголовками или курсивом. Именно поэтому вставлять логи ошибок или конфиги следует в блок кода.

Ловушка перевода строки

В стандартном Markdown одиночный перевод строки не даёт перенос — для нового абзаца нужна пустая строка, для принудительного переноса — два пробела в конце. Это неудобно для тех, кто привык свободно переносить строки.

Поэтому здесь по умолчанию включён пункт «одиночный перевод строки тоже переносит», что соответствует интуиции. Если вы готовите документ, который обязан строго соответствовать стандарту (например, для генератора статических сайтов), снимите флажок.

Когда использовать Markdown

• Хорошо подходит: техническая документация, README, заметки со встреч, требования, черновики постов, личные заметки — всё насыщенное содержанием, бедное вёрсткой и поддерживаемое со временем.
• Менее хорошо: официальные документы, где нужен тонкий контроль вёрстки, сочетание текста и изображений или многоколоночный дизайн. Для них классический текстовый процессор прямее.

Экспорт и перенос

Есть три выхода:

• Копировать Markdown: исходный текст, вставляется где угодно, где поддерживается Markdown.
• Копировать HTML: отрендеренный фрагмент HTML, готовый к вставке на вашу страницу. Учтите, что он не несёт таблицу стилей — CSS для красоты поставляете вы.
• Скачать .md: сохраняется файлом для контроля версий или архива.

Всё происходит в браузере, и ничего из написанного не покидает ваш компьютер. Для проверки откройте панель «Сеть» по F12 — при наборе не отправляется ни одного запроса.

Связанные инструменты