Карта сайта вместо неявных маршрутов

Решение

Описывать страницы в одном файле config/sitemap.yml. Каждая запись задаёт заголовок, URL, исходный файл и необязательные метаданные, например layout.

Контекст

Для сайта документации важны заданный порядок страниц, структура адресов и навигация. Каталог контента может содержать черновики и ассеты, которые не должны автоматически становиться страницами.

Альтернативы

Маршруты из путей файлов. Они сокращают ручную регистрацию, если структура каталогов совпадает с нужными URL. Порядок страниц и метаданные навигации всё равно нужно где-то описать.

Метаданные в каждом файле. URL и сведения о вёрстке можно хранить рядом с документом. Так локальные настройки остаются рядом с контентом, но общую структуру сайта сложнее проверить в одном месте.

Явное дерево страниц. Оно добавляет шаг регистрации, зато отделяет опубликованные адреса от расположения исходников Markdown.

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

Движок готовит хлебные крошки по сегментам URL и карты соответствия файлов Markdown адресам для междокументных ссылок. Один исходный файл может иметь несколько адресов; мост выбирает подходящего кандидата или сообщает о неоднозначности.

Карта сайта передаёт layout как метаданные страницы. Зарегистрированный обработчик документа и шаблоны сайта решают, как их использовать; ядро не выбирает блок вёрстки по умолчанию.

Последствия

Добавление файла Markdown само по себе не публикует страницу: нужна запись в карте сайта. Список публикации становится явным, но содержимое зарегистрированных страниц всё равно требует проверки.

По мере роста сайта карту нужно редактировать и поддерживать. Для автоматически создаваемых или динамических маршрутов может лучше подойти другая модель.