docs
|
|
| Сайт |
https://docs.dvxch.team (/en/…, /ru/…) |
| API |
https://docs.dvxch.team/api/v1 (nav, pages, search, meta), публичный |
| Для языковых моделей |
/llms.txt, /llms-full.txt, <страница>.md, MCP на /mcp |
Что делает
- Документация установленной версии: страницы встроены в бинарник, поэтому всегда соответствуют тому, что
запущено на инстансе, и используют его домен в примерах.
- Два языка — по адресу, сохранённому выбору или языку браузера.
- Поиск по заголовкам, разделам и тексту (⌘K или
/).
- Читается без JavaScript: каждая страница рендерится на сервере, со ссылками на другую языковую версию
для поисковиков, картой сайта и
robots.txt.
- Markdown для каждой страницы: допишите
.md к адресу или нажмите Скопировать страницу.
- MCP-инструменты
search_docs и read_doc для агентов.
- Внешний вид инстанса: имя, логотип, акцентный цвет и фон из home, статья поверх фона — на стеклянной
карточке.
- Публичная: вход не нужен.
Как писать документацию
Страницы — Markdown в репозитории docs (content/en, content/ru). make serve запускает сайт из рабочей
копии и перезагружает его при каждом сохранении. Формат (front matter, выноски, вкладки, шаги, карточки)
описан в services/docs.md репозитория, в разделе Internals.
Документация команд (v2)
Откройте docs.dvxch.team/spaces и создайте пространство команды: документацию продукта, вики,
описание API. Начните с пустого или с шаблона (документация продукта, вики команды, описание API) либо
импортируйте папку с Markdown или экспорт Notion, GitBook, Docusaurus или MkDocs — порядок навигации
сохранится.
Разработчики команды пишут и публикуют, наблюдатели читают черновики и комментируют, администраторы
управляют доступом и настройками. Гостей не из команды можно пригласить в одно пространство
редакторами или комментаторами.
Как писать
Страницы пространства — в боковой панели под его разделами: нажмите, чтобы открыть, перетащите, чтобы
изменить порядок или вложить, ⋯ — добавить подстраницу, переименовать, дублировать, перенести (в том
числе в другое пространство команды), скрыть или удалить (корзина хранит страницы 30 дней). Страница
открывается во всю ширину, как в блокноте:
- Наберите
/, чтобы вставить блок — заголовки, списки, задачи, цитаты, примечания, код, вкладки, шаги,
карточки, таблицы, изображения, файлы, встраивания, описания API, ссылки на страницы, — или пишите
Markdown (## , - , ```). Вставленный Markdown превращается в блоки.
- Выделите текст — появится панель: жирный, курсив, зачёркнутый, код, ссылка, AI, комментарий.
- Наведите на блок — появится ручка: перетащить, добавить блок ниже, дублировать или удалить.
- Писать можно вместе и видеть курсоры друг друга; офлайн-правки сливаются после переподключения.
- Комментарии и История — справа вверху страницы: комментарии привязаны к тексту, с ответами,
упоминаниями и решением; любую прежнюю версию можно сравнить и восстановить.
У каждого языка пространства свой текст страницы; язык переключается над страницей. Читатели видят язык
по умолчанию, пока перевода нет.
Публикация
Читатели никогда не видят черновик. Опубликовать показывает изменения по страницам и предупреждает о
битых ссылках; публикация после этого не меняется, даже когда обновляется движок. В Публикациях можно
вернуть прежнюю, назвать публикацию версией (v1), которую читатели выбирают в шапке сайта, или
восстановить её как черновик. Предпросмотр открывает черновик так, как его увидит читатель.
Доступ и настройки
- Настройки → Доступ: команда и гости, все, кто вошёл на инстанс, все по секретной ссылке (по желанию
с паролем) или все подряд. Доступ в меню пространства приглашает гостей и создаёт ссылки на
пространство или одну страницу, со сроком и паролем.
- Настройки → Свои домены: каждое пространство доступно на
<адрес>.docs.dvxch.team; Подключить
домен открывает xvii domains, который создаст записи и сертификат.
- Настройки → Оформление: название, логотип, значок, акцентный цвет, фон, ссылки в шапке и подвале,
лендинг для главной. Что не задано, берётся из оформления инстанса.
- Настройки → Основное: вопрос читателям «Страница помогла?» и Считать читателей — сайт в xvii
analytics для пространства (без cookies). В Статистике — отзывы и поиски, которые ничего не нашли.
- Настройки → Источник Git: храните страницы в репозитории GitLab или GitHub; вебхук переносит каждый пуш в
черновик, такие страницы редактируются в репозитории. Когда репозиторий отключён, Сделать редактируемыми
превращает его страницы в обычные страницы пространства.
AI
В Настройки → AI кнопка Подключить xvii AI даёт пространству собственный ключ команды (копировать
ничего не нужно; при отключении ключ отзывается) и выбирает модель. AI в редакторе переписывает,
сокращает, исправляет, продолжает, переводит на другой язык пространства или кратко описывает страницу —
всегда как предложение, которое вы проверяете. AI-ответы читателям позволяют задавать вопросы по
опубликованным страницам и получать ответы со ссылками на них. Расход учитывается в AI-лимитах команды.
Описания API
Вставьте блок Описание API или импортируйте документ OpenAPI 3 (JSON или YAML, файлом или по адресу
HTTPS): страница покажет методы с параметрами, схемами и примерами на curl, JavaScript, Python и Go.
Отправить запрос обращается к API прямо из браузера читателя (API должен разрешать CORS); через docs
ничего не идёт, учётные данные не сохраняются. Документ фиксируется с каждой публикацией.
Из терминала, CI и для агентов
xvii docs spaces # пространства ваших команд
xvii docs create "Handbook" --template wiki
xvii docs publish ./docs --space product # папка с Markdown становится черновиком и публикуется
xvii docs pull --space product docs # черновик обратно в Markdown
В CI входят через XVII_TOKEN или OIDC-токен задачи (по правилам доверия команды в id). Агенты могут
работать через docs.dvxch.team/mcp с токеном: список пространств и страниц, чтение, создание и
изменение страниц из Markdown, публикация.