Core Concepts

title: Core concepts description: The core Doxbrix model: workspaces, projects, spaces, navigation, pages, states, and the publishing lifecycle.

Doxbrix is easier to use once you understand the small number of concepts it repeats everywhere. The same model drives the editor, the CLI, the published site, permissions, localization, AI features, and the API. This page defines that model in practical terms.

The hierarchy

The most important distinction is this: a workspace is your team's administrative container, while a project is a single documentation property that readers actually consume.

Workspace

A workspace is the top-level container for your organization. It owns the people, policies, and shared controls that sit above any single documentation site.

Typical workspace responsibilities include:

• managing members and roles
• controlling billing and plan usage
• setting workspace-wide AI policy and budgets
• defining shared defaults for new projects
• configuring security and authentication policies

In other words, if a setting should apply across several documentation sites, it usually belongs at the workspace level.

Manage these controls in Settings → Workspace. Related pages include Workspace AI policy and Members & roles.

Project

A project is one documentation site or knowledge base. It is the main unit authors work in and the main unit readers visit.

Everything that makes one site different from another is defined here:

• spaces, groups, and pages
• branding and theme
• domain and publishing settings
• visibility and reader authentication
• editor mode
• locales and translation structure
• project-level assistant and support settings

A single workspace commonly holds several projects — for example a public Product Docs site, a private Internal Knowledge Base, and a customer Help Center.

This separation is useful operationally. It lets one team maintain several documentation experiences without duplicating users, billing, or workspace-wide governance.

Spaces

A space is the top navigation layer inside a project. Each space appears in the reader-facing top bar and carries its own sidebar context. Use spaces for major content domains, not for minor categorization.

Good examples of spaces:

• Documentation
• Guides
• API Reference
• Admin
• Changelog

Poor examples of spaces:

• one space per small feature
• one space per short page series
• spaces created only to compensate for weak page grouping

Groups, pages, and navigation

Within a space, the sidebar is assembled from a compact set of navigation node types. These are the building blocks of reader navigation and author information architecture.

You build and rearrange all of these in the content tree in the editor — see Spaces & navigation.

The design principle here is separation of concerns:

• a page is the content itself
• a group organizes related pages
• a label separates sections visually
• an API node represents a reference-style entry with method semantics

This makes it easier to scale a site without flattening everything into one long sidebar.

Pages

A page is one document with its own title, body, status, route, revision history, and metadata. In practical terms, it is the main unit of authoring, reviewing, and publishing.

You can create pages from templates such as Blank, Guide, API reference, or FAQ, then write them with the blocks and components supported by Doxbrix.

Under the hood, a page is MDX: Markdown plus Doxbrix components. That matters because it gives you portability between the visual editor and the CLI docs-as-code workflow.

Page states

Every page has a workflow state, shown in both the content tree and the page header. This state controls whether the content is still being worked on, awaiting approval, or visible to readers.

Two distinctions are important:

• saved is not the same as published
• unpublished is not the same as deleted

This lets teams maintain live documentation with editorial control instead of treating the site as a direct mirror of whatever someone last typed.

Draft, review, and publish as separate operations

Doxbrix intentionally separates the content lifecycle into different operations:

1. Editing changes the draft.
2. Review adds comments, suggestions, and approvals.
3. Publishing changes what readers can access.

That separation supports stronger governance, especially for customer-facing or regulated documentation where not every edit should go live immediately.

Editor modes

A project uses one of two editing surfaces, configured in Settings → Project:

• Block editor (default) — a structured canvas where you insert blocks from the / palette, with drag-and-drop and diagrams.
• WYSIWYG editor — a document-style surface with a formatting toolbar, closer to a word processor.

Both write the same underlying content model. That means the choice of editor affects the authoring experience, but not the long-term portability of the documentation.

Use the Block editor when you want a structured docs experience with reusable layouts and rich blocks. Use WYSIWYG when your team prefers a more traditional document-editing interaction.

How these concepts connect to readers

The hierarchy above is not just an internal authoring model. Readers experience it directly:

• projects define the site they visit
• spaces define the top-level sections they switch between
• groups and pages define the sidebar they navigate
• published state defines what content they can see
• AI and search operate against the content you have structured and published

That is why good information architecture in Doxbrix pays off twice: it improves the authoring workflow and makes the reader experience easier to search, browse, and trust.

Next steps