Руководство по Markdown
Markdown — это легковесный язык разметки, созданный для удобного чтения и написания текста с последующим преобразованием в HTML. Ниже представлен полный справочник по синтаксису Markdown, адаптированный для ведения вики-документации.
1. Заголовки
Заголовки создаются с помощью символа #. Количество # определяет уровень заголовка (от 1 до 6).
# Заголовок 1 уровня
## Заголовок 2 уровня
### Заголовок 3 уровня
#### Заголовок 4 уровня
##### Заголовок 5 уровня
###### Заголовок 6 уровня
Совет: Заголовки 1 и 2 уровня можно также подчеркнуть знаками = и - соответственно, но вариант с # более распространён.
2. Абзацы и переносы строк
Абзацы разделяются пустой строкой:
Это первый абзац.
Это второй абзац.
Для переноса строки внутри абзаца добавьте два пробела в конце строки или используйте <br>.
3. Форматирование текста
Элемент | Синтаксис | Результат |
|---|
Жирный | **текст** или __текст__
| жирный текст |
Курсив | *текст* или _текст_
| курсивный текст |
Жирный курсив | ***текст***
| жирный курсив |
Зачёркнутый
| ~~текст~~
| зачёркнутый
|
Код (inline)
| `код`
| моноширинный
|
==Подсветка== | ==текст==
| (поддерживается не везде) |
<u>Подчёркнутый</u> | <u>текст</u>
| Подчёркнутый (HTML) |
H2O (нижний индекс) | H~2~O
| H₂O |
X2 (верхний индекс) | X^2^
| X² |
4. Списки
Ненумерованный список
- Элемент 1
- Элемент 2
- Вложенный элемент 2.1
- Вложенный элемент 2.2
- Элемент 3
Альтернативные символы: * или +.
Нумерованный список
1. Первый пункт
2. Второй пункт
1. Вложенный пункт
2. Вложенный пункт
3. Третий пункт
Список задач (Task List)
- [x] Выполненная задача
- [ ] Невыполненная задача
- [ ] Ещё одна задача
5. Ссылки
Внешние ссылки
[текст ссылки](https://example.com)
[текст ссылки](https://example.com "Всплывающая подсказка")
Внутренние ссылки (якоря на заголовки)
[Перейти к разделу](#заголовок-раздела)
Заголовок в якоре: все буквы строчные, пробелы заменяются на -, спецсимволы удаляются.
Автоматические ссылки
<https://example.com>
<user@example.com>
Сноски (не везде поддерживаются)
Текст со сноской.[^1]
[^1]: Текст самой сноски.
6. Изображения
Изображение-ссылка
[](https://example.com)
Размер изображения (HTML)
<img src="изображение.png" alt="Описание" width="300" />
7. Код
Inline-код
Используйте команду `sudo pacman -Syu` для обновления.
Блок кода
def hello():
print("Привет, мир!")
Поддерживается подсветка синтаксиса для большинства языков: python, bash, json, html, css, javascript, cpp, java, yaml и многих других.
Блок кода без языка
обычный текст
без подсветки
8. Цитаты (Blockquotes)
> Это цитата.
> Она может занимать несколько строк.
> Можно вкладывать цитаты:
>> Вложенная цитата
>>> Ещё глубже
Цитаты с оформлением (блоки-заметки)
Часто используются в вики для выделения важной информации:
> **ℹ️ Примечание:** Это полезная дополнительная информация.
> **💡 Совет:** Это рекомендация, которая может пригодиться.
> **⚠️ Предупреждение:** Будьте осторожны при выполнении этой операции.
> **🚫 Опасность:** Действие может привести к необратимым последствиям!
9. Таблицы
| Заголовок 1 | Заголовок 2 | Заголовок 3 |
|---|---|---|
| Ячейка 1 | Ячейка 2 | Ячейка 3 |
| Ячейка 4 | Ячейка 5 | Ячейка 6 |
Выравнивание в таблицах
| По левому краю | По центру | По правому краю |
|:---|:---:|---:|
| Текст | Текст | Текст |
| Длинный текст | Текст | 123 |
Синтаксис выравнивания:
:--- — по левому краю:---: — по центру---: — по правому краю
10. Горизонтальная линия (разделитель)
---
***
___
Все три варианта дают одинаковый результат — горизонтальную линию.
11. Экранирование символов
Если нужно отобразить символ, который используется в синтаксисе Markdown, поставьте перед ним обратную косую черту \:
\* Это не курсив \*
\# Это не заголовок
\[Это не ссылка\]
Экранировать можно: \, *, _, {, }, [, ], (, ), #, +, -, ., !, |, ~.
12. HTML в Markdown
Markdown позволяет вставлять чистый HTML для расширенных возможностей:
<details>
<summary>Нажмите, чтобы развернуть</summary>
Скрытое содержимое. Здесь может быть **Markdown** внутри HTML-блока.
</details>
<kbd>Ctrl</kbd> + <kbd>C</kbd>
Текст с <mark>подсветкой</mark> и <ins>подчёркиванием</ins>.
Результат:
<details>
<summary>Нажмите, чтобы развернуть</summary>
Скрытое содержимое. Здесь может быть Markdown внутри HTML-блока.
</details>
13. Диаграммы (Mermaid)
Многие вики-движки (GitHub, GitLab, Notion) поддерживают диаграммы через Mermaid:
flowchart TD
A[Начало] --> B{Условие?}
B -->|Да| C[Действие 1]
B -->|Нет| D[Действие 2]
C --> E[Конец]
D --> E
flowchart TD
A[Начало] --> B{Условие?}
B -->|Да| C[Действие 1]
B -->|Нет| D[Действие 2]
C --> E[Конец]
D --> E
Доступные типы: flowchart, sequenceDiagram, classDiagram, stateDiagram, gantt, pie, mindmap, timeline.
Mindmap (интеллект-карта)
mindmap
root((Тема))
Раздел 1
Подраздел 1.1
Подраздел 1.2
Раздел 2
Подраздел 2.1
Подраздел 2.2
14. Математические формулы (LaTeX)
Поддерживается в GitHub, GitLab, Notion и других:
Инлайн-формула: $E = mc^2$
Блочная формула:
$$
\int_{a}^{b} f(x)\,dx = F(b) - F(a)
$$
15. Содержание (Table of Contents)
Некоторые платформы автоматически генерируют содержание:
## Содержание
- [Заголовки](#1-заголовки)
- [Форматирование текста](#3-форматирование-текста)
- [Ссылки](#5-ссылки)
На GitHub можно использовать:
- [ ] Содержание
16. Эмодзи (Emoji)
:smile: :rocket: :warning: :white_check_mark: :x: :fire: :bulb:
Результат: 😄 🚀 ⚠️ ✅ ❌ 🔥 💡
Полный список эмодзи: Emoji Cheat Sheet.
17. Комментарии (невидимый текст)
<!-- Это комментарий, он не отображается -->
[//]: # (Это тоже комментарий)
[комментарий]: #
18. Быстрый конвертер: MediaWiki → Markdown
MediaWiki | Markdown |
|---|
= Заголовок =
| # Заголовок
|
== Заголовок ==
| ## Заголовок
|
=== Заголовок ===
| ### Заголовок
|
'''жирный'''
| **жирный**
|
''курсив''
| *курсив*
|
[[Страница]]
| [Страница](Страница)
|
[[Страница\|Текст]]
| [Текст](Страница)
|
[url текст]
| [текст](url)
|
{{note\|текст}}
| > **ℹ️ Примечание:** текст
|
{{warning\|текст}}
| > **⚠️ Предупреждение:** текст
|
{{tip\|текст}}
| > **💡 Совет:** текст
|
{{UserCmd\|command=...}}
| ```bash ...```
|
{{ic\|команда}}
| `команда`
|
<code>код</code>
| `код`
|
<br>
| пустая строка или <br> |
19. Практические советы
- Всегда оставляйте пустую строку перед и после заголовков, списков и блоков кода — это улучшает читаемость исходника и совместимость.
- Используйте осмысленный альтернативный текст для изображений (
) — это важно для доступности.
- Не смешивайте Markdown и HTML без необходимости — чем проще, тем надёжнее.
- Проверяйте результат в целевом движке: разные платформы могут по-разному обрабатывать одни и те же конструкции.
- Для крупной документации используйте MkDocs, Docusaurus или Hugo с Markdown-файлами — они поддерживают больше расширений, чем GitHub/GitLab.
- Таблицы сложнее трёх столбцов часто удобнее описывать списками или схемами Mermaid.
Смотрите также
