Управление заголовками

Заголовки разрешаются по жёсткой трёхуровневой иерархии:

Приоритет Источник Область Переопределение

1

Файл компонента docs/*/antora.yml

Имя и версия компонента

Переопределяет всё

2

Playbook antora-playbook-*.yml

Брендинг сайта

Переопределяет документы

3

Атрибуты внутри .adoc

Отдельный файл

Самый низкий

Заголовки на уровне компонента

Файл docs/en/antora.yml

name: en
title: Adaptadocx Documentation
version: '1.0'
display_version: '1.0'

asciidoc:
  attributes:
    component-title: '{title}'
    component-version: '{version}'
    document-title: '{component-title} {component-version}'

Русский компонент в docs/ru/antora.yml оформлен аналогично (локализованные строки, name: ru).

Атрибут Назначение

title

Подпись в левой навигации

version

Машиночитаемая версия

display_version

Человекочитаемая версия

component-title

Переиспользуемый атрибут

document-title

Шаблон для производных заголовков

Заголовки на уровне playbook

Фрагмент antora-playbook-en.yml

site:
  title: Adaptadocx Documentation
  start_page: en::index.adoc

asciidoc:
  attributes:
    site-title: '{site.title}'
    page-title-pattern: '{site-title} - {page-title}'

Русский playbook antora-playbook-ru.yml зеркален и использует локализованные значения.

Атрибут Назначение

site.title

Основной HTML <title>

site-title

Переиспользуемый атрибут

page-title-pattern

Глобальный шаблон HTML-<title>

Заголовки на уровне документа

Внутри любого .adoc-файла:

= Архитектура системы
:navtitle: Архитектура
Атрибут Эффект Можно переопределить

= Title

H1 в отрендеренном контенте

Метаданные могут меняться

:navtitle:

Пункт меню

Может быть заменён навигацией компонента (nav.adoc)

Обработка при выводе

  • HTML — <title> определяется по page-title-pattern → значения компонента → заголовок документа.

  • PDF — заголовок/версия берутся из атрибутов компонента; Makefile передаёт -a revnumber=<version>.

  • DOCX — метаданные загружаются из config/meta-en.yml / config/meta-ru.yml; для каждой версии Makefile создаёт временный файл build/docx/meta-<locale>-<version>.yml с подстановкой 0.1.0.

Диагностика

  • Несогласованные заголовки — проверьте title/version компонента и атрибуты playbook.

  • Неверный заголовок/версия в PDF — проверьте использование -a revnumber в Makefile и настройки темы config/default-theme.yml.

  • Несоответствие меню и страницы — корректируйте :navtitle: или nav.adoc компонента.

См. также