Как использовать формат Markdown для сайтов
Markdown — это простой текстовый формат для хранения контента в вебе. Он похож на обычный формат .txt, только в нём используются специальные символы для оформления залоговков, ссылок, картинок, списков, разных начертаний текста и тому подобное. Формат создан для того, чтобы этот контент легко преобразовывался в теги HTML, из которых состоят сайты.
Преимущества Markdown
- Писать текст с форматированием проще и быстрее, чем в HTML.
- Файлы в Markdown легко читать даже без преобразования.
- Markdown можно конвертировать в HTML или другие форматы, с ним работают многие инструменты.
- Меньше шансов на синтаксические ошибки, чем в HTML.
Где используется
Markdown используют на многих больших сайтах и приложениях. Например среди них: GitHub, Reddit, Stack Overflow, Notion, Medium. Фреймворки позволяют хранить в нём контент сайтов, особенно это удобно для статей блогов, документаций, README-файлов. Ещё дальше пошёл новый фреймворк Nue, в котором все страницы создаются в Markdown, с расширенными возможностями для добавления вложенных блоков и компонентов.
Также данный сайт и эта самая статья хранятся преимущественно в Markdown.
Все элементы Markdown и примеры их использования
На компьютере можно создать обычный Текстовый документ.txt и переименовать его расширение в Текстовый документ.md — вот и готов файл в формате Markdown, который можно открывать и редактировать в обычном приложении Блокнот. Для удобства можно использовать онлайн-редактор, например такой.
Общее правило: все элементы нужно разделять между собой пустой строкой. Далее показаны все возможности оформления текста.
Абзацы
Просто текст в одно или несколько предложений. Два разных параграфа нужно разделять пустой строкой.
Это один абзац.
Это другой абзац <br>
с переносом строки.
Подробнее
Этот пример преобразуется в следующий HTML:
<p>Это один абзац.</p>
<p>Это другой абзац <br>с переносом строки.</p>Заголовки
Для создания заголовков используйте знак # перед текстом. Количество таких решёток будет означать уровень заголовка, от первого до шестого.
# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
Подробнее
Этот пример преобразуется в следующий HTML:
<h1>Заголовок 1 уровня</h1>
<h2>Заголовок 2 уровня</h2>
<h3>Заголовок 3 уровня</h3>Выделение текста
Текст можно выделять: жирный, курсив, зачёркнутый и пример кода.
**жирный**, *курсив*, ~~зачёркнутый~~ и `пример кода`.
Подробнее
Этот пример преобразуется в следующий HTML:
<p><strong>жирный</strong>, <em>курсив</em>, <s>зачёркнутый</s> и <code>пример кода</code>.</p>Списки
Для создания маркированного списка используются символы - или + или *. Для нумерованного списка цифры с точкой 1..
- Первый пункт маркированного списка.
- Второй пункт маркированного списка.
1. Первый пункт нумерованного списка.
2. Второй пункт нумерованного списка.
Подробнее
Этот пример преобразуется в следующий HTML:
<ul>
<li>Первый пункт маркированного списка.</li>
<li>Второй пункт маркированного списка.</li>
</ul>
<ol>
<li>Первый пункт нумерованного списка.</li>
<li>Второй пункт нумерованного списка.</li>
</ol>Ссылка
Ссылки создаются с помощью такой конструкции: [текст ссылки](url).
Это [ссылка](https://mitorun-studio.ru/) внутри строки.
[Ссылка отдельным абзацем.](https://mitorun-studio.ru/services/)
Подробнее
Этот пример преобразуется в следующий HTML:
<p>Это <a href="https://mitorun-studio.ru/">ссылка</a> внутри строки.</p>
<p><a href="https://mitorun-studio.ru/services/">Ссылка отдельным абзацем.</a></p>Изображение
Картинки вставляются очень похоже на ссылки, только вначале пишется восклицательный знак: . Дополнительно рядом с url можно добавить атрибут title.
Подробнее
Этот пример преобразуется в следующий HTML:
<p><img src="/img/example.jpg" alt="Картинка для примера" title="title"></p>Блок с цитатой
В статьях встречается такой элемент, как блок с цитатой.
> Это цитата.
Подробнее
Этот пример преобразуется в следующий HTML:
<blockquote><p>Это цитата.</p></blockquote>Блок с кодом
Можно вставлять блок с кодом, дополнительно к нему можно указать язык кода.
```md
Блок с кодом в формате Markdown.
```
Подробнее
Этот пример преобразуется в следующий HTML:
<pre><code class="language-md">Блок с кодом в формате Markdown.
</code></pre>Особенности: Если нужно показать блок с кодом маркдауна, как в примере выше, то для внешнего блока нужно записать по 4 апострофа, а внутреннему блоку стандартные 3.
Разделительная черта
Разделительную черту можно создать с помощью трёх тире.
---
Подробнее
Этот пример преобразуется в следующий HTML:
<hr>Комментарий
Если какой-то текст нужно закомментировать, чтобы он оставался в файле, но не показывался на сайте — его нужно обернуть в HTML-тег для комментариев.
<!-- Комментарий к коду -->
Таблицы
В расширенном синтаксисе можно вставлять таблицы.
| Номер | Продукт | Количество |
|:------|:-------:|-----------:|
| 1 | Банан | 5 |
| 2 | Стакан | 214 |
Другие возможности
Если символы, которые используются для разметки, нужно показать в контенте — их можно экранировать, вставив перед ними \. Внутри одного параграфа можно вставить перенос строки, для этого строку нужно закончить двумя пробелами и начать со следующей строки. Следующий пример показывает обе эти возможности.
\*\*Экранирование звёзд\*\*
**\*\*Экранирование звёзд, но с жирным текстом\*\***
Подробнее
Этот пример преобразуется в следующий HTML:
<p>**Экранирование звёзд**<br><strong>**Экранирование звёзд, но с жирным текстом**</strong></p>Оформления можно комбинировать. Например выделить ссылку жирным, курсивом и примером кода, эту ссылку поместить внутрь списка который находится внутри цитаты.
> - [***Ссылка***](https://mitorun-studio.ru/)
> - [***Ссылка 2***](https://mitorun-studio.ru/services/)
Внутри файлов .md можно вставлять обычный код HTML и создавать конструкции любой сложности, когда обычных возможностей Markdown не хватает.
Выше описаны стандартные возможности Markdown. Есть ещё расширенные возможности, например создание таблиц, но они поддерживаются уже не везде.