Concepts

Concepts

This page defines every word the rest of the documentation depends on.

Workspace

A company, an organisation or one person. A workspace holds the members, the billing, the integrations, the audit log and the projects. A person can belong to many workspaces.

Project

One documentation property: Product Docs, an API reference, a help centre, an engineering handbook. A project owns its pages, its navigation, its theme, its domain, its search, its analytics and its repository connection.

Your plan sets how many projects a workspace may have. See Limits.

Page

One Markdown file under pages/. Its path is its URL: pages/guides/install.md is served at /guides/install. pages/api/index.md is served at /api.

A page carries frontmatter: its title, its description, its review schedule, its owner.

Site file

The five YAML files a project keeps beside its pages, plus the navigation:

nav.yaml, variables.yaml, search.yaml, redirects.yaml, glossary.yaml, style.yaml.

They are content. They are staged, committed, reviewed, published and exported exactly like a page. They are not prose, so the editor opens them as YAML rather than as a document.

Branch

A change request. Every draft lives on one. Name it for the topic, in the form draft/<who>/<slug>.

Staged

Written, but not yet in git history. A staged change is visible in the writer and to the agent that made it. Nothing else can see it.

Commit

History, on a branch. A commit runs the linter first and refuses if the tree would be broken.

Publish

A merge to the default branch. Publishing is the only step a machine cannot do.

Pulse

The part of the product that decides what is going stale. It reads your pages, your code and your OpenAPI documents, then reports which pages describe something that has changed. See Pulse.

Scope

What a token is allowed to do: docs:read, docs:write or docs:commit. A token also names one project. See Tokens.