Configuration
DocPlatform follows a convention-over-configuration approach. It runs with sensible defaults out of the box, but every aspect is configurable for production deployments.
Configuration layers
Configuration is applied in three layers, from broadest to most specific:
| Layer | Scope | Method |
|---|---|---|
| Environment variables | Platform-wide | .env file or shell environment |
| Workspace config | Per workspace | .docplatform/config.yaml |
| Page frontmatter | Per page | YAML block in each .md file |
Higher-specificity layers override lower ones. For example, a page’s access.read rules restrict visibility beyond the workspace-level defaults.
Guides
| Guide | What it covers |
|---|---|
| Environment Variables | All platform-level settings: port, data directory, git, SMTP, telemetry |
| Workspace Settings | Per-workspace config: git remote, theme, navigation, publishing defaults |
| Authentication | Local auth, OIDC providers (Google, GitHub), JWT settings, password policies |
| Roles & Permissions | 5-level RBAC hierarchy, page-level access control, and permission caching |
Quick reference
The most common configuration tasks:
| Task | Where |
|---|---|
| Change the server port | PORT environment variable |
| Connect a git repository | Workspace config git_remote |
| Enable Google/GitHub sign-in | OIDC_* environment variables |
| Set up email (invitations, password reset) | SMTP_* environment variables |
| Change the default role for new users | Workspace config permissions.default_role |
| Restrict published docs to team members only | PUBLISH_REQUIRE_AUTH=true environment variable |
| Restrict a page to specific roles (web editor) | Page frontmatter access.read: ["role-name"] |
| Disable telemetry | DOCPLATFORM_TELEMETRY=off |