Шаблоны страниц

Шаблон задаёт страницам одного вида один и тот же набор разделов: какие разделы ## есть, в каком порядке и какие из них обязательны. Так читатель находит одно и то же в одном и том же месте на каждой странице справочника, а человек и ИИ-помощник пишут новые страницы одинаково.

Профиль говорит, к какому типу относится страница, например справочник, и проверяет общие признаки: есть ли таблица или список. Шаблон точнее: он называет сами разделы. У шаблона может быть профиль, и тогда страница по шаблону получает и его.

Шаблоны необязательны. Пока шаблон не назначен ни одной странице, Docara ничего нового не проверяет.

Пример

Шаблон для страниц компонентов и правило, которое назначает его всем страницам каталога components/:

{
  "schema": "docara.authoring.v1",
  "templates": {
    "component": {
      "description": "Страница компонента в справочнике.",
      "profile": "reference",
      "sections": [
        {"id": "example", "heading": "Пример", "required": true, "example": true},
        {"id": "markup", "heading": "Разметка", "required": true,
         "hint": "Минимальная правильная разметка и обязательные части."},
        {"id": "variants", "heading": "Варианты", "example_per_subsection": true},
        {"id": "accessibility", "heading": "Доступность", "required": true},
        {"id": "classes", "heading": "Классы", "required": true, "generated": true},
        {"id": "see-also", "heading": "См. также"}
      ]
    }
  },
  "rules": [
    {"match": "components/**", "template": "component"}
  ]
}

Страница по этому шаблону начинается с заголовка # и короткого вступления, затем идут разделы ## Пример, ## Разметка и дальше по списку. Разделы «Варианты» и «См. также» можно не писать, остальные обязательны.

Поля шаблона

Какой странице какой шаблон

Шаблон страницы определяется так, первое подходящее срабатывает:

1. template во front matter страницы.
2. Правило в rules с полем template, путь которого подходит странице.

Если странице подходят правила с разными шаблонами, проверка остановится с AUTHORING_RULE_CONFLICT. В одном правиле можно указать и profile, и template.

---
template: component
---

# Кнопка

Если раздела на странице нет нарочно, например у компонента нет своих классов, перечислите его id в template_omit:

---
template_omit: [classes]
---

Что проверяет docara validate page

docara validate page сравнивает разделы ## страницы с шаблоном и сообщает о каждом расхождении отдельным кодом. Заголовки внутри блоков кода не считаются, а якорь {#id} в конце заголовка не мешает.

Как и замечания профиля, они не останавливают сборку. В отчёте docara qa report они попадают в одно замечание QUALITY_TEMPLATE_MISMATCH и снижают оценку полноты страницы.

php vendor/bin/docara validate page /ru/components/button/ --json

Новая страница по шаблону

docara scaffold page --template создаёт страницу со всеми разделами шаблона по порядку:

php vendor/bin/docara scaffold page components/badge --template=component --title="Значок"

В заготовке:

• template и профиль шаблона во front matter и draft: true;
• текст-подсказка во вступлении и в каждом разделе;
• подсказка из hint — HTML-комментарием, на сайте её не видно;
• пустая генерируемая область в генерируемом разделе;
• подсказка добавить живой пример там, где он нужен.

Замените подсказки, допишите примеры и удалите draft: true. Отчёт docara qa report находит подсказки, которые остались на странице. Заготовка по шаблону и заготовка по источнику документации не совмещаются: укажите что-то одно.

Генерируемые разделы

Генерируемый раздел пишет программа проекта, например таблицу классов из CSS или справочник API из манифеста. Человек этот раздел не правит: чтобы изменить его, меняют исходный код или программу.

Программа пишет раздел между двумя метками, каждая на своей строке:

## Классы

<!-- docara:generated -->
| Класс | CSS |
| --- | --- |
| `sf-button` | `display: inline-flex` |
<!-- /docara:generated -->

Заголовок раздела можно поставить и внутри меток, если программа пишет раздел целиком. Метки работают на любой странице, не только в разделах шаблона. Генерируемая область не влияет на актуальность перевода: программа перестраивает её на каждом языке сама. Метки без пары останавливают проверку с PAGE_TEMPLATE_GENERATED_REGION_INVALID.

Ошибки файла

См. также

• Профили страниц — тип страницы и docara.authoring.json
• Метаданные страницы — ключи template и template_omit
• Качество документации — оценка от 0 до 100