Bezdepbonusu7Программирование: статьи и ответы

Разметка текста

Синтаксис Markdown: шпаргалка с примерами для начинающих

Markdown - простой текстовый формат разметки для README, документации и заметок. Ниже шпаргалка синтаксиса: таблица "как написать и что получится", заголовки, списки, ссылки, код, таблицы и чек-листы GitHub Flavored Markdown.

Синтаксис Markdown: шпаргалка с примерами для начинающих
Содержание
  1. Что такое Markdown
  2. Шпаргалка: как написать и что получится
  3. Заголовки, абзацы и переносы строк
  4. Выделение текста и списки
  5. Ссылки и картинки
  6. Код в Markdown
  7. Таблицы в Markdown
  8. Чек-листы, цитаты и дополнительные возможности GFM
  9. Экранирование и HTML
  10. Чем писать и открывать Markdown
  11. Преобразование Markdown в HTML, PDF и Word
  12. Частые вопросы

Что такое Markdown

Markdown - это простой текстовый формат разметки: вы пишете обычный текст и расставляете знаки вроде #, * и -, а программа превращает их в заголовки, выделение и списки. Файлы Markdown имеют расширение .md и открываются любым текстовым редактором. Формат придумали, чтобы исходник читался глазами даже без преобразования.

Где он применяется: файлы README в репозиториях, документация проектов, описания задач и пулл-реквестов, заметки в Obsidian и других редакторах, ячейки текста в тетрадях Jupyter. Если вы работаете с кодом, Markdown вам понадобится быстро. Например, оформить описание проекта на GitHub без него не получится.

У формата есть несколько диалектов. Оригинальный синтаксис описал Джон Грубер, затем появился стандарт CommonMark, который однозначно определяет правила. GitHub Flavored Markdown (GFM) - расширение CommonMark с таблицами, чек-листами, зачёркиванием и автоссылками. Большинство примеров ниже работают и в CommonMark, и в GFM, а отдельные расширения помечены.

Шпаргалка: как написать и что получится

В таблице собраны основные конструкции. В левом столбце - то, что нужно набрать, в правом - результат после обработки.

Как написатьЧто получится
# ЗаголовокЗаголовок первого уровня (h1)
## ЗаголовокЗаголовок второго уровня (h2), и так до шести решёток
**текст**жирный текст
*текст* или _текст_курсив
***текст***жирный курсив
~~текст~~зачёркнутый текст (GFM)
- пункт или * пунктмаркированный список
1. пунктнумерованный список
[текст](https://example.com)ссылка с подписью "текст"
![описание](img.png)картинка с альтернативным текстом
`код`короткий фрагмент кода в строке
> цитатаблок цитаты
--- на отдельной строкегоризонтальная линия
- [ ] задача и - [x] готовочек-лист с флажками (GFM)

Перед решёткой и после неё нужен пробел: #Заголовок без пробела в CommonMark заголовком не считается. Между блоками разного типа, например абзацем и списком, оставляйте пустую строку, иначе разные редакторы могут обработать текст по-разному.

Заголовки, абзацы и переносы строк

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

# Название проекта

Короткое описание в одном абзаце.

## Установка

### Через pip

Абзацы отделяются пустой строкой. Если просто нажать Enter внутри абзаца, большинство обработчиков склеит две строки в одну. Чтобы получить перенос внутри абзаца, закончите строку двумя пробелами или обратной косой чертой. В комментариях и описаниях задач на GitHub достаточно одного Enter, но в файлах репозитория работает правило с пробелами или косой чертой.

Выделение текста и списки

Жирный текст получается двойными звёздочками или двойными подчёркиваниями, курсив - одинарными. Внутри слова надёжнее звёздочки: подчёркивания в середине слов во многих обработчиках не работают.

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

- Фрукты
  - Яблоки
  - Бананы
- Овощи

1. Скачать архив
2. Распаковать
3. Запустить установку

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

Ссылки и картинки

Ссылка записывается как текст в квадратных скобках и адрес в круглых. Картинка - то же самое с восклицательным знаком впереди. Вместо относительного пути можно указать полный адрес.

[Документация Python](https://docs.python.org/3/)
[Подсказка при наведении](https://example.com "Заголовок ссылки")
![Скриншот окна](images/screen.png)

<https://example.com>

Ссылка со ссылочным стилем: [читать][doc]

[doc]: https://docs.python.org/3/

Адрес в угловых скобках превращается в ссылку с самим адресом в качестве текста. Ссылочный стиль удобен, когда один адрес повторяется несколько раз: определение [doc]: ... пишется отдельной строкой в любом месте документа. На GitHub обычный адрес вида https://... превращается в ссылку и без скобок.

Для картинок всегда заполняйте альтернативный текст в квадратных скобках: он показывается, если файл не загрузился, и читается программами экрана.

Код в Markdown

Короткий фрагмент оборачивается в одинарные обратные кавычки (backtick), блок кода - в три. После трёх кавычек в начале блока можно указать язык: так включится подсветка синтаксиса. Этот способ называется fenced code block, он есть в CommonMark и GFM.

Запустите `python main.py` в терминале.

```python
def hello(name):
    return f"Привет, {name}!"

print(hello("мир"))
```

Название языка после кавычек - python, js, bash, json, sql - зависит от того, какую подсветку поддерживает конкретная программа. Если нужно показать в блоке саму тройную кавычку, оборачивайте его в четыре обратные кавычки. Исходный отступ из четырёх пробелов тоже даёт блок кода, но такой способ считается устаревшим: язык подсветки при нём не указать.

Если вы пишете Markdown в редакторе кода, пригодится настройка VS Code: в нём есть встроенный предпросмотр, он открывается сочетанием Ctrl+Shift+V.

Таблицы в Markdown

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

| Язык       | Тип        | Год |
|:-----------|:----------:|----:|
| Python     | Динамический | 1991 |
| Go         | Статический  | 2009 |

Двоеточия во второй строке задают выравнивание: слева от дефисов - по левому краю, с обеих сторон - по центру, справа - по правому. Ровно выравнивать пробелами столбцы в исходнике не обязательно, это нужно только для удобства чтения. Если в ячейке нужна сама вертикальная черта, экранируйте её обратной косой чертой.

Переносов строк внутри ячейки в таблице нет: для этого используют тег <br>, если обработчик разрешает HTML. Составлять большие таблицы вручную неудобно, лучше пользоваться редактором с помощью или генератором.

Чек-листы, цитаты и дополнительные возможности GFM

Чек-листы пишутся как обычный список с квадратными скобками. Пробел внутри скобок означает невыполненную задачу, буква x - выполненную. На GitHub такие флажки можно переключать мышью в описании задачи.

- [x] Написать README
- [ ] Добавить примеры
- [ ] Проверить ссылки

> Цитата занимает отдельный блок.
> Её можно продолжать на следующей строке.

Цитата начинается со знака >, вложенные цитаты - с двух таких знаков. Внутри цитаты работает остальная разметка: списки, выделение, код.

Ещё несколько возможностей GFM, которые встречаются в документации. Сноски в стиле [^1] с определением ниже. Автоматические ссылки на задачи и пользователей: #123 и @username. Блоки предупреждений в описаниях на GitHub, например > [!NOTE] и > [!WARNING] с текстом на следующих строках. Это возможности конкретной платформы: в других редакторах они могут отображаться как обычная цитата.

Экранирование и HTML

Если нужно вывести символ, который Markdown воспринимает как разметку, поставьте перед ним обратную косую черту: \*не курсив\*, \# не заголовок. Экранировать можно звёздочки, подчёркивания, решётки, скобки, кавычки-бэктики и другие служебные знаки.

Многие обработчики позволяют вставлять обычный HTML, если разметки не хватает, например для картинки определённого размера или для сворачиваемого блока. Но возможности разных платформ отличаются, и часть тегов на них отфильтровывается: GitHub, например, удаляет скрипты и стили. Поэтому HTML внутри Markdown лучше использовать редко и проверять в предпросмотре.

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

Слева исходный текст Markdown, справа готовый результат после обработки
Исходник Markdown и то, что показывает предпросмотр

Чем писать и открывать Markdown

Писать можно в любом текстовом редакторе. Но удобнее программы с живым предпросмотром, где слева исходник, а справа готовый вид. Варианты бывают такие.

СпособДля чего удобен
VS Code, PyCharm и другие средыREADME и документация рядом с кодом, предпросмотр в отдельной вкладке
Онлайн-редакторы Markdownбыстро проверить разметку без установки
Редакторы заметокличные записи, ссылки между заметками
Jupyter Notebookтекстовые ячейки рядом с кодом
Репозиторий на GitHubфайл README.md отображается автоматически на странице проекта

В тетрадях Jupyter Notebook ячейка с типом Markdown использует тот же синтаксис, поэтому заметки с заголовками и формулами оформляются точно так же.

Преобразование Markdown в HTML, PDF и Word

Из Markdown можно получить другие форматы. Для документов, PDF и Word популярна универсальная программа pandoc: она читает .md и сохраняет в нужный формат по расширению выходного файла.

pandoc README.md -o README.html
pandoc README.md -o README.docx

Первая команда создаёт HTML-страницу, вторая - документ Word. Для PDF pandoc дополнительно требует установленный механизм вёрстки, например LaTeX, поэтому проще открыть файл в редакторе с предпросмотром и распечатать в PDF.

Из Python Markdown превращается в HTML с помощью пакета markdown. Установите его командой python -m pip install markdown.

import markdown

text = """# Привет

Это **Markdown**.

| a | b |
|---|---|
| 1 | 2 |
"""

html_text = markdown.markdown(text, extensions=["tables", "fenced_code"])
print(html_text)

Расширение tables включает поддержку таблиц, а fenced_code - блоки кода в тройных кавычках. Программа выведет HTML с тегами h1, p, strong и table. Если вам нужно сохранить результат в файл, помните про кодировку: открывайте файл с параметром encoding="utf-8", подробнее об этом в статье про кодировку UTF-8.

Если Markdown лежит в репозитории, изменения в нём отслеживаются так же, как в коде. Основные команды для этого собраны в шпаргалке по командам Git.

Частые вопросы

Что такое Markdown и для чего он нужен?

Это формат разметки, где заголовки и выделение задаются простыми символами, например # и **. Его применяют для README, документации, заметок и описаний задач.

Чем открыть файл .md?

Любым текстовым редактором. Для просмотра с оформлением подойдут редакторы кода с предпросмотром, онлайн-редакторы Markdown и GitHub, который показывает README.md на странице репозитория.

Как сделать таблицу в Markdown?

Разделите столбцы вертикальной чертой, а под строкой заголовка добавьте строку из дефисов, например |---|---|. Двоеточия в ней задают выравнивание.

Как вставить код в Markdown?

Короткий фрагмент оберните в одинарные обратные кавычки, блок - в три обратные кавычки с названием языка в первой строке.

Чем GitHub Flavored Markdown отличается от обычного?

GFM добавляет таблицы, чек-листы, зачёркнутый текст, автоссылки и некоторые функции платформы GitHub, например ссылки на задачи.

Как преобразовать Markdown в PDF или Word?

Воспользуйтесь программой pandoc, например pandoc file.md -o file.docx. PDF проще получить печатью из редактора с предпросмотром.

Как сделать перенос строки в Markdown?

Закончите строку двумя пробелами или обратной косой чертой, либо оставьте пустую строку между абзацами.

Источники

  • CommonMark Spec, CommonMark
  • GitHub Flavored Markdown Spec, GitHub
  • Basic writing and formatting syntax, GitHub Docs

Похожие материалы

Версии программ и команды проверены на дату публикации. Если что-то изменилось, сверяйтесь с официальной документацией. Нашли неточность? Напишите на admin@bezdepbonusu7.win.