Reborn 8.x

[tabuna]

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

Навигация

Предлагаю отказаться от ручного составления оглавлений в наших файлах документации и перейти к их автоматической генерации. Система будет создавать оглавления на основе заголовков второго, третьего и четвертого уровней (h2, h3, h4 и т.д.). Это нововведение позволит достичь следующих целей:

• Повысить эффективность поддержания актуальности переводов благодаря автоматизации;
• Достигнуть унификации формата текстов, обеспечив единообразие заголовков и ссылок;
• Извлечь оглавления в отдельный блок, что предоставит нам возможность их скрывания для пользователей, впервые знакомящихся с документацией.

Данная инициатива не окажет влияния на якорные ссылки, ведущие на другие страницы. Существующие теги для якорей, например:

<a name="generating-migrations"></a>

Останутся нетронутыми и будут функционировать как прежде, сохраняя стабильность перекрёстных ссылок в документации. Переводчику не нужно будет забояться о перекрёстных url и он по-прежнему сможет беззаботно копировать.

Переменные

Кроме того, предлагаю пересмотреть формат внедрения хешей коммитов. Вместо текущего варианта:

git XXXX

----

Я предлагаю использовать более гибкий и информативный формат в стиле YAML, который позволит нам встраивать переменные и дополнительные данные прямо в текст документации:

---
git: XXXX
---

Это позволит нам добавлять ключевые слова, заголовки и другие важные метаданные в формате:

---
title: "Заголовок страницы <title>"
keywords: artisan, console
git: XXXX
---

Для наглядной иллюстрации как это выглядит в IDE: