Представьте книгу без оглавления, глав и подзаголовков. Технически текст есть — но ориентироваться в нём почти невозможно. С документацией и README происходит то же самое. Даже хороший текст становится сложным для восприятия, если в нём нет чёткой структуры. Именно заголовки отвечают за эту структуру — они показывают, где начинается новая тема, как части связаны между собой и что в документе главное.

В этом уроке вы научитесь использовать заголовки в Markdown не просто «для красоты», а как инструмент навигации и логики.

Что вы узнаете в рамках статьи

После этого урока вы:

• разберётесь, какие бывают уровни заголовков в Markdown
• поймёте, как выстраивать логическую иерархию документа
• научитесь читать и проектировать структуру текста ещё до написания
• узнаете типичные ошибки с заголовками и как их избежать

Ключевые термины

Перед началом зафиксируем основные понятия:

• Заголовок — элемент текста, обозначающий начало смыслового блока
• Уровень заголовка — степень вложенности заголовка (H1, H2, H3 и т.д.)
• Иерархия документа — логическая структура текста от общего к частному
• H1–H6 — стандартные уровни заголовков в Markdown
• Навигация по документу — возможность быстро понять структуру и найти нужный раздел

Уровни заголовков в Markdown

В Markdown заголовки создаются с помощью символа #. Количество этих символов в начале строки определяет уровень заголовка и его место в иерархии документа.

Базовый синтаксис выглядит так:

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня

Здесь важно не столько запомнить синтаксис, сколько понять логику. Чем меньше символов #, тем выше уровень заголовка и тем более общую тему он обозначает. И наоборот: чем больше #, тем заголовок становится более конкретным и вложенным.

Как это читать с точки зрения структуры

Проще всего представить заголовки как дерево или оглавление книги:

• # — название всего документа, одна большая тема
• ## — крупные разделы внутри этой темы
• ### — подразделы, раскрывающие детали
• #### и ниже — ещё более узкие части, которые используются реже

Например, структура README может выглядеть так:

# My Project
## Установка
## Запуск
## Конфигурация
### Переменные окружения
### Файл конфигурации

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

Сколько уровней использовать на практике

Markdown поддерживает до шести уровней заголовков (#–######). Но это не значит, что их все нужно применять.

В реальных проектах чаще всего хватает:

• одного заголовка первого уровня,
• двух–трёх уровней вложенности для разделов и подразделов.

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

Заголовки как «скелет» документа

Заголовки в Markdown — это не просто надписи над текстом. Это скелет документа, его внутренняя конструкция. Как у здания есть несущие стены, так у текста есть заголовки, на которых держится всё остальное.

Хороший способ проверить структуру документа — мысленно убрать весь текст и оставить только заголовки. Если в таком виде по документу всё ещё можно «пройтись» и понять, о чём он и как устроен, значит, структура выбрана правильно.

По одним только заголовкам должно быть ясно:

• какая основная тема у документа,
• какие разделы в нём есть,
• как эти разделы связаны между собой и в каком порядке идут.

Рассмотрим пример:

# Проект X
## Установка
## Запуск
## Конфигурация
### Переменные окружения
### Режимы работы
## Частые ошибки

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

Именно так заголовки превращаются в навигацию. Читатель может быстро найти нужный раздел, не читая всё подряд, а автор — заранее продумать логику изложения.

Markdown в этом месте работает как инструмент мышления: он помогает сначала спроектировать структуру, а уже потом наполнять её содержанием. И чем сложнее документ, тем важнее этот «скелет», на который он опирается.

Логическая структура текста

Правильная иерархия заголовков — это всегда движение от общего к частному. Сначала читателю показывают крупную тему, затем её части, а уже потом — детали и нюансы.

Такой подход интуитивно понятен: человек сначала хочет понять, о чём вообще речь, и только после этого углубляться. Заголовки как раз и задают этот маршрут чтения.

В Markdown эта логика напрямую отражается в уровнях заголовков. Посмотрите на пример:

## Работа с конфигурацией
### Файл config.yaml
### Переменные окружения

С первого взгляда ясно, что оба подзаголовка относятся к одной общей теме — работе с конфигурацией. Читателю не нужно догадываться или перечитывать текст, чтобы восстановить связи между разделами.

Важно помнить: заголовки — это не способ «сделать текст крупнее» или визуально выделить фрагмент. Это способ обозначить смысловые уровни. Если уровень выбран неправильно, структура ломается: читатель теряет ориентацию и вынужден тратить усилия на понимание того, как части документа связаны между собой.

Markdown в этом смысле работает как инструмент дисциплины. Он заставляет заранее продумывать структуру текста и выстраивать её осознанно, а не добавлять заголовки в самом конце «для порядка». Именно поэтому хорошо структурированный Markdown-документ читается легче и воспринимается логичнее — даже при большом объёме текста.

Типичные ошибки с заголовками

Ошибка 1. Пропуск уровней

# Заголовок
### Подзаголовок

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

Ошибка 2. Использовать заголовки ради внешнего вида

Заголовок — не инструмент форматирования. Если хочется выделить текст визуально — для этого есть другие средства. Заголовок должен обозначать новую тему, а не просто выглядеть крупнее.

Ошибка 3. Несколько H1 в одном документе

В README или статье обычно должен быть один главный заголовок:

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

Все остальные темы — ниже по иерархии.

Из практики: README с хаотичными заголовками читается так же тяжело, как код без отступов.

Наиболее частые вопросы

• Сколько уровней заголовков нужно использовать?
  Ровно столько, сколько нужно для логики. Чаще всего 2–4 уровня более чем достаточно.
• Можно ли пропускать уровни, если так «красивее»?
  Технически можно, но логически — почти всегда ошибка.
• Заголовки влияют только на внешний вид?
  Нет. Они влияют на навигацию, восприятие текста и даже на автогенерацию оглавлений.

Итоги

Сегодня вы разобрались:

• как работают заголовки в Markdown
• чем отличаются уровни заголовков
• как с их помощью выстраивается иерархия документа
• какие ошибки чаще всего портят структуру текста

Заголовки — это основа любого технического текста. Они помогают читателю быстро ориентироваться, а автору — ясно мыслить и структурировать материал. В следующем уроке мы продолжим работать со структурой и перейдём к выделению текста и акцентам, чтобы научиться подчёркивать главное, не перегружая документ.