Как добавить статью

Список статей на главной мануала не зашит в шаблон вручную. Движок читает папку articles, подхватывает PHP-файлы с массивом метаданных и строит карточки. Новый мануал — это новый файл. Правки видны сразу, отдельная «сборка» или деплой фронта не нужны.

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

Имя файла и URL

Имя задаёт адрес. Файл 25-payments.php откроется как /payments. Число в начале нужно для порядка на диске и удобства людей, смотрящих папку. Сортировку в каталоге на сайте задаёт поле sort, не число в имени. Не меняйте slug после индексации без редиректа: внешние ссылки и привычка команды сломаются.

Слаг — латиница, дефисы, без пробелов и кириллицы в URL. Имя файла = {sortHint}-{slug}.php по принятому у вас шаблону.

Поля массива

• title — заголовок карточки и страницы.
• category — раздел; новый раздел сам появится в фильтрах.
• sort — позиция в ленте, меньше число — выше.
• excerpt — короткий текст на карточке.
• query, seo_title, seo_description, keywords — SEO-поля, если используются в шаблоне.
• html — тело статьи в heredoc <<<'HTML'.

Заголовки h2 внутри html попадают в оглавление справа. Не пропускайте уровни ради «красоты» (h2 → h4 без h3), если оглавление строится просто.

Heredoc HTML

Тело пишите валидным HTML-фрагментом: p, h2, ul, ol, div class="note", ссылки. Внутри heredoc с одинарными кавычками 'HTML' переменные PHP не интерполируются — удобно для текста. Не вставляйте закрывающий маркер HTML на отдельной строке внутри текста статьи.

Внутренние ссылки — только пути мануала вида /birzha-frilansa, не абсолютные чужие зеркала. Картинки кладите туда, куда уже принято в проекте, с понятными alt.

Стиль текста

Практический тон: шаги, проверки, ошибки. Меньше воды и общих лозунгов. Длина для посадочных мануалов — ориентир 850–1200 слов полезного текста, если статья закрывает продуктовый кластер. Короткие служебные заметки могут быть короче, но тогда честно держите их в разделе «Старт» или «Сервис».

Не дублируйте title слово в слово в первом абзаце трижды. Не обещайте функции, которых нет в продукте. Если ссылаетесь на соседний мануал — проверьте, что файл существует.

Добавление по шагам

1. Скопируйте ближайший по типу файл статьи как шаблон.
2. Поменяйте имя файла и slug.
3. Обновите метаданные: title, category, sort, excerpt, SEO-поля.
4. Замените только тело html.
5. Откройте главную мануала — карточка должна появиться.
6. Откройте URL статьи, проверьте оглавление и ссылки.
7. Прогоните текст на опечатки и битые якоря.

Сортировка и категории

Если карточка «не там», смотрите sort и category. Одинаковые sort — порядок может быть нестабильным; держите запас уникальности. Новая категория не требует правки шаблона фильтров — появится сама, но не плодите синонимы («Старт» и «Начало»).

Безопасность папки

Папка статей закрыта от прямого просмотра снаружи как сырые PHP-исходники через веб в нормальной конфигурации: отдача идёт через каталог мануала. Не кладите в articles секреты, пароли, приватные ключи. Это контент, не .env.

Проверка качества перед публикацией

Прочитайте статью вслух или через сутки свежим глазом. Проверьте: все ссылки открываются, код в code не ломает вёрстку, списки не пустые, note-блоки не дублируют абзац выше один в один. SEO-title не должен быть копией H1 с пятью лишними ключами.

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

Если статья заменяет старую, не удаляйте файл молча: редирект или обновление содержимого на том же slug. Команда и поисковик любят стабильные URL. Для черновиков локально можно держать суффикс -draft в имени, но на боевом мануале лучше не светить недописанное — либо не выкладывайте файл, либо не включайте в выдачу, если появится флаг публикации.

После добавления обновите связанные статьи ссылками туда-обратно. Одинокий текст без входящих ссылок в мануале живёт хуже.

Совместная работа и git

Если мануал в git, не редактируйте один и тот же файл параллельно без связи. Конфликт в heredoc неприятнее, чем в коде. Договоритесь о владельце статьи. В коммите пишите slug и суть, не «fix texts».

Не коммитьте временные скрипты подчёркиванием вроде служебных генераторов в articles, если они не часть продукта — вычищайте после работы. Боевой каталог должен содержать только статьи.

Перед большим пакетом новых материалов прогоните скрипт подсчёта слов и проверку, что каждый файл парсится (return array без синтаксической ошибки). Один битый PHP может уронить весь список, если лоадер не изолирует исключения — проверьте поведение на стенде намеренно битым файлом в копии, не на проде.

Шаблоны note и списков

Блок div class="note" используйте для одного важного предупреждения, не для каждого абзаца. Списки — для проверяемых шагов и перечней полей; не превращайте всю статью в маркированный поток. Абзацы разной длины читаются живее, чем идеально ровные «нейросетевые» секции. В конце полезен один практический итог, без мотивационного лозунга.

Перед коммитом большого пакета статей просмотрите главную: карточки не должны выглядеть клонами с одинаковым excerpt. Уникальный excerpt — часть работы, не мелочь.

Быстрый самотест файла

Откройте статью в браузере, сверните окно до ширины телефона, проверьте таблицы и длинные строки кода. Убедитесь, что оглавление из H2 не пустое и что note не прилип к предыдущему списку без смысла. Если лоадер кэширует — обновите страницу принудительно. На это уходит две минуты и спасает от «на главной карточка есть, внутри каша».