Your First Workspace

A workspace is the top-level container for a documentation project. Each workspace maps to a directory of Markdown files and optionally syncs with a git repository.

Workspace concepts

Create a workspace

Via CLI

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

Via web UI

1. Sign in as Super Admin or Admin
2. Open the workspace switcher (top-left dropdown)
3. Click Create Workspace
4. Enter a name and slug
5. Optionally configure a git remote

Connect a git repository

Bidirectional sync keeps your workspace files and a remote git repository in lockstep.

During initialization

docplatform init \
  --workspace-name "Engineering Docs" \
  --slug eng-docs \
  --git-url git@github.com:your-org/eng-docs.git \
  --branch main

After creation

Update the workspace config at .docplatform/workspaces/{id}/.docplatform/config.yaml:

git_remote: git@github.com:your-org/eng-docs.git
git_branch: main
git_auto_commit: true
sync_interval: 300  # seconds

Then restart the server or trigger a manual sync from the web UI.

SSH key setup

For private repositories, DocPlatform uses a dedicated 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)

Set the environment variable:

export GIT_SSH_KEY_PATH=~/.ssh/docplatform_deploy_key

How sync works

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

Web → Git: When you save in the editor, DocPlatform writes the .md file, auto-commits with a descriptive message, and pushes to the remote.

Git → Web: DocPlatform polls the remote (default: every 5 minutes) or listens for webhooks. New commits are pulled and the web UI updates in real-time via WebSocket.

Conflicts: If both sides change the same file between syncs, DocPlatform detects the collision using content hashes, returns HTTP 409, and makes both versions downloadable so you can resolve manually.

Organize your content

Page hierarchy

Pages can be nested to any depth. The file structure in docs/ maps directly to the URL structure:

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

Every page starts with YAML frontmatter:

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

The title is required. All other fields are optional and have sensible defaults.

Invite your team

Via web UI

1. Open Workspace Settings → Members
2. Click Invite
3. Enter the person’s email address
4. Select a role (Viewer, Commenter, Editor, Admin)
5. Click Send Invitation

If SMTP is configured, the invitation is sent by email. Otherwise, a shareable invitation link is displayed.

Roles

For detailed permission configuration, see Roles & Permissions.

Workspace settings

Access workspace settings through the web UI (Settings gear icon) or by editing the config file directly.

Key settings:

For the complete configuration reference, see Workspace Settings.

What’s next

Your workspace is ready. Here’s where to go from here: