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

Руководство по Markdown в документации

Краткая сводка по использованию Markdown в проекте на Docusaurus: структура файлов, основы разметки, возможности Docusaurus и правила обхода опасных символов. Полную документацию можно прочитать здесь Markdown features

1. Структура каждого файла документации​

Для единообразия придерживайтесь такой структуры:

Front matter — в самом начале файла, между двумя строками из трёх дефисов ---:

  • Обязательно: sidebar_position (число) — задаёт порядок страницы в сайдбаре.
  • По желанию: title, description — если нужны для SEO или отображения в плагине docs.

После закрывающего --- оставьте пустую строку.

Далее идёт контент:

  • Один заголовок H1 (#) в начале — он задаёт заголовок страницы.
  • Затем заголовки H2–H6, параграфы, списки и т.д.
  • Рекомендуется оставлять пустую строку между логическими блоками (после заголовков, между параграфами и списками).

Пример начала файла:

---
sidebar_position: 4
---

# Заголовок страницы

Первый параграф текста...

2. Основы Markdown (шпаргалка)​

  • Заголовки: # — H1, ## — H2, … ###### — H6.
  • Выделение: **жирный**, *курсив*, `код` (обратные кавычки).
  • Ссылки: [текст](url), изображения: ![alt](url).
  • Списки: маркированные — - или *; нумерованные — 1., 2. и т.д.
  • Цитаты: строка начинается с >.
  • Блок кода: три обратные кавычки, затем (по желанию) язык, затем код, затем три обратные кавычки, например ```bash.
  • Горизонтальная линия: --- на отдельной строке.

Подробнее: CommonMark Help.

3. Возможности Docusaurus для авторов​

Admonitions (примечания)​

Синтаксис через три двоеточия: :::note, :::tip, :::info, :::caution, :::warning, :::danger. Блок закрывается ещё одним :::. Опциональный заголовок — в квадратных скобках: :::note[Заголовок].

В этом проекте используется именно такой синтаксис. Стиль Obsidian (> [!NOTE] и т.п.) в Docusaurus не поддерживается — используйте :::note и аналоги.

Пример:

:::tip
Подсказка: внизу страницы есть кнопка «Отредактировать эту страницу».
:::
подсказка

Подсказка: внизу страницы есть кнопка «Отредактировать эту страницу».

Front matter (YAML)​

Метаданные в начале файла между ---. В проекте используются поля: sidebar_position, при необходимости title, description.

Подсветка кода​

В блоках кода укажите язык после открывающих трёх обратных кавычек (например ```bash, ```text) — Docusaurus использует Prism для подсветки.

Подробнее: Markdown Features | Docusaurus, Admonitions.

4. Чем Markdown в Docusaurus отличается от обычного (MDX)​

Файлы .md в Docusaurus обрабатываются как MDX: в них можно вставлять JSX и JavaScript-выражения. Из-за этого часть символов имеет особый смысл:

  • Угловые скобки < и > воспринимаются как начало и конец тега (JSX/HTML). Текст вроде «нажмите < Извлечь>» или «команда с параметром <path>» парсер может принять за тег — возможны ошибка сборки или некорректный вывод.
  • Фигурные скобки { и } воспринимаются как JavaScript-выражения. Написание в тексте {переменная} приведёт к попытке выполнить код и к ошибке или поломке отображения.

Подробнее: Troubleshooting MDX (раздел про экранирование < и {).

5. Опасные символы: как писать безопасно​

В обычном тексте не используйте буквальные <, >, {, } там, где парсер может воспринять их как JSX или выражение.

Способы обхода:

  1. Экранирование обратным слэшем: \<, \>, \{, \} — для одиночных символов в тексте (рекомендация MDX).
  2. Инлайн-код: оберните фрагмент в обратные кавычки, например `команда <path>`, `set var=<name>`, `{expression}` — тогда парсер не интерпретирует их как теги или выражения.
  3. Блок кода: для длинных команд, путей или плейсхолдеров используйте тройные обратные кавычки с указанием языка.

Примеры:

Как не надо (может сломать сборку)Как надо
В меню выберите < Извлечь>В меню выберите Извлечь или напишите < Извлечь >
Используйте <USERNAME> и <TOKEN>Используйте `USERNAME` и `TOKEN` или экранируйте: <USERNAME>, <TOKEN>
Переменная в фигурных скобках в обычном текстеПеременная `{value}` или {value} в тексте

6. Итоговые рекомендации по проекту​

  • Соблюдайте единую структуру файла: front matter → H1 → контент.
  • Используйте admonitions только в синтаксисе Docusaurus (:::), не в стиле Obsidian.
  • При упоминании путей, команд, плейсхолдеров с <, >, {, } — экранируйте их или пишите в `коде` / в блоке кода.
  • Для единого стиля оформления см. стандарты оформления.