Concepts

Version

A version is an immutable published revision of an API, schema, ruleset, site, or SDK/CLI package. Uploading a new OpenAPI document or syncing a site creates a new version while keeping history.

Public docs can expose a version switcher over recent site publishes (?v=). That is separate from registry versions for OpenAPI history.

Slug

Stable URL-safe identifiers:

• Organization resources use slugs in console URLs and APIs

• Sites use a slug for {slug}.pinnate.app

• Guide pages use path-based or frontmatter slugs under a section

• SDK embeds in site.yaml resolve by SDK slug (or id / name)

Section

A site section is a top-nav entry:

• Guide — Markdown tree under a path

• Embed — live API reference, SDK docs, or CLI docs

• Group — label-only parent with child sections (for example More → SDKs)

Embed

An embed pulls a live view from another resource into the site shell. Guides stay Markdown; reference UIs stay generated from published content.

Visibility

Sites (and registry resources) can be public or private. Public sites are readable without signing in. Private sites require organization membership. See Authentication.

Frontmatter

Optional YAML at the top of Markdown files controls title, slug, description, sidebar position, and hidden. See Page settings.

Sync root

The directory (or file) path on a connected git remote that Pinnate imports. For sites, the root should contain site.yaml when you use docs-as-code navigation.