Ваш первый workspace

Workspace — это контейнер верхнего уровня для проекта документации. Каждый workspace соответствует директории с Markdown-файлами и опционально синхронизируется с git-репозиторием.

Концепции workspace

Создание workspace

Через CLI

docplatform init \
  --workspace-name "Engineering Docs" \
  --slug eng-docs

Через веб-интерфейс

1. Войдите как Super Admin или Workspace Admin
2. Откройте переключатель workspace (выпадающий список вверху слева)
3. Нажмите Create Workspace
4. Введите имя и slug
5. Опционально настройте удаленный git-репозиторий

Подключение git-репозитория

Двунаправленная синхронизация поддерживает файлы workspace и удаленный git-репозиторий в актуальном состоянии.

При инициализации

docplatform init \
  --workspace-name "Engineering Docs" \
  --slug eng-docs \
  --git-url [email protected]:your-org/eng-docs.git \
  --branch main

После создания

Обновите конфигурацию workspace по адресу .docplatform/workspaces/{id}/.docplatform/config.yaml:

git_remote: [email protected]:your-org/eng-docs.git
git_branch: main
git_auto_commit: true
sync_interval: 300  # seconds

Затем перезапустите сервер или запустите ручную синхронизацию через веб-интерфейс.

Настройка SSH-ключа

Для приватных репозиториев DocPlatform использует выделенный SSH deploy key:

# Generate a deploy key (no passphrase)
ssh-keygen -t ed25519 -f ~/.ssh/docplatform_deploy_key -N ""

# Add the public key to your repository's deploy keys
cat ~/.ssh/docplatform_deploy_key.pub
# → Copy this to GitHub/GitLab Settings → Deploy Keys (enable write access)

Установите переменную окружения:

export GIT_SSH_KEY_PATH=~/.ssh/docplatform_deploy_key

Как работает синхронизация

┌─────────────┐     auto-commit + push      ┌──────────────┐
│ Web Editor   │ ──────────────────────────► │ Remote Repo  │
│ (browser)    │                             │ (GitHub, etc)│
│              │ ◄────────────────────────── │              │
└─────────────┘     polling / webhook        └──────────────┘

Web -> Git: При сохранении в редакторе DocPlatform записывает файл .md, автоматически коммитит с описательным сообщением и пушит в удаленный репозиторий.

Git -> Web: DocPlatform опрашивает удаленный репозиторий (по умолчанию: каждые 5 минут) или слушает webhook. Новые коммиты подтягиваются, и веб-интерфейс обновляется в реальном времени через WebSocket.

Конфликты: Если обе стороны изменяют один и тот же файл между синхронизациями, DocPlatform обнаруживает коллизию с помощью хешей контента, возвращает HTTP 409 и делает обе версии доступными для скачивания, чтобы можно было разрешить конфликт вручную.

Организация контента

Иерархия страниц

Страницы могут быть вложены на любую глубину. Структура файлов в docs/ напрямую соответствует структуре URL:

docs/
├── index.md                → /p/eng-docs/
├── getting-started.md      → /p/eng-docs/getting-started
├── api/
│   ├── index.md            → /p/eng-docs/api/
│   ├── authentication.md   → /p/eng-docs/api/authentication
│   └── endpoints.md        → /p/eng-docs/api/endpoints
└── guides/
    ├── deployment.md       → /p/eng-docs/guides/deployment
    └── contributing.md     → /p/eng-docs/guides/contributing

Frontmatter

Каждая страница начинается с блока YAML frontmatter:

---
title: Authentication
description: How to authenticate with the API using JWT tokens.
tags: [api, auth, jwt]
published: true
access:
  roles: []           # empty = all workspace members (default)
  users: []           # restrict by @user_id
---

Поле title является обязательным. Все остальные поля опциональны и имеют разумные значения по умолчанию.

Приглашение команды

Через веб-интерфейс

1. Откройте Workspace Settings -> Members
2. Нажмите Invite
3. Введите email-адрес приглашаемого
4. Выберите роль (Viewer, Commenter, Editor, Admin)
5. Нажмите Send Invitation

Если настроен SMTP, приглашение отправляется по email. В противном случае отображается ссылка-приглашение для совместного использования.

Роли

Подробнее о настройке прав доступа смотрите в разделе Роли и права доступа.

Настройки workspace

Управляйте настройками workspace через веб-интерфейс (значок шестеренки Settings) или редактируя файл конфигурации напрямую.

Основные настройки:

Полный справочник конфигурации смотрите в разделе Настройки workspace.

Что дальше

Ваш workspace готов. Куда двигаться дальше: