Як писати документацію порталу

Документація порталу лежить у репозиторії, а не в базі. Причина проста: текст змінюється разом із поведінкою, яку описує · той самий коміт, те саме рев'ю, той самий відкат.

Де лежать файли

Каталог public-docs/ у корені проєкту. Кожен документ · один .md-файл. Шлях файла стає адресою сторінки:

public-docs/admin/about-page.md  ->  /docs/admin/about-page

У шляху дозволені лише малі латинські літери, цифри, дефіс і слеш. Документ із іншим імʼям портал пропустить.

Обережно з окремими словами в адресі. Веб-сервер має захисні правила й блокує деякі шляхи ще до застосунку · зокрема ті, що містять install. Такий документ віддаватиме 403, хоча в каталозі він є. Якщо сторінка існує, а відкривається 403 · перейменуйте файл (наприклад, install → installation) і поправте посилання на нього.

Front matter

Кожен файл починається блоком метаданих:

---
title: Назва сторінки
description: Один рядок для списку й для пошукової видачі.
category: admin
order: 20
audience: Адміністратори
updated: 2026-08-15
---

• title обовʼязковий · без нього документ не збереться;
• category має збігатися з ключем у public-docs/manifest.json; невідома категорія просто додасться в кінець списку;
• order задає порядок усередині категорії, менше · вище.

Що можна в тексті

Звичайний Markdown: заголовки, списки, таблиці, цитати, блоки коду, посилання. Заголовки другого й третього рівня автоматично отримують якорі й потрапляють у зміст сторінки.

Сирий HTML у документі вирізається. Це навмисно: вміст файла не має ставати розміткою сторінки, навіть якщо файл пройшов рев'ю.

Скріншоти

Зображення лежать у public/docs-media/ і підключаються звичайним Markdown:

![Сторінка релізів](/docs-media/admin/releases.png)

Зображення з інших адрес прибираються під час збірки · вигляд сторінки не має залежати від чужого сервера, а запит до нього видавав би читача.

Місце під майбутній скріншот

Поки знімка ще немає, місце під нього позначається окремим абзацом:

[СКРІН]: сторінка релізів, видно список кандидатів і кнопку публікації.

Такий абзац перетворюється на видиму рамку з описом того, що має бути на знімку. Це краще за невидиме «потім додам»: намір зафіксований, і його видно всім, включно з читачем.

Місце для скріншота

Як зміни потрапляють на сайт

Портал перечитує каталог, коли змінюється склад або вміст файлів. Локально правка .md видно одразу після перезавантаження сторінки; на бойовому сервері · після деплою. Окрему кнопку «перебудувати» натискати не потрібно.

Зіпсований документ не ламає портал: він пропускається, решта каталогу лишається цілою.

Чого не варто робити

• дублювати в документації те, що вже написано в інтерфейсі · воно розійдеться;
• описувати плани як наявну поведінку;
• вставляти реальні дані користувачів у приклади й скріншоти.