Pages

A Page represents a single content document, which you read and change through the Pages API. You can think of each page as a single resource and should group related content, or content likely to be read together into pages.

Each page:

• Lives within a directory

• Contains sections that hold the actual content

• Has permissions controlling who can access and modify it

type Page {  id: ID!                         # Unique identifier  slug: String!                   # URL-friendly identifier  path: String!                   # Full path from the root  directory: String!              # Directory path (e.g., "/docs/api/")  title: String                   # Optional display title  author: User                    # User who created the page  metadata: PageMetadata!         # Publishing state and timestamps  children: [Section!]!           # Top-level content sections  sections: SectionConnection!    # Every section, at any depth, with its place in the tree  permissions: PagePermissions!   # Access controls}

Pages can be referenced in two different ways: by id or by slug.

• Page IDs: are randomly generated, immutable strings, generated by our API. This means once a page has been created it won't ever be changed and is particularly great for hardcoding links between pages.

• Slugs: are human-readable, URL-safe identifiers that you define to name pages and express site structure. They are stable for linking and navigation, but can be updated when your content or structure evolves.

Pages have some data that is updated automatically:

• Directory: page directory is auto-generated based on the page's slug and will be used to co-locate similar pages. For example, a page could be stored at /docs/pages and another page at /docs/users, both have the directory /docs. More about directories below.
• Author: the user who created the page. It is a record of who created it, not a permission: what anyone can do with a page is decided by its permissions alone, so an author has no special access. If no user was involved (for example, the page was created by an application calling the API as itself), author is null.
• Timestamps and publishing: metadata records when the page was created and last changed, and whether it is published. updatedAt moves whenever the page's content changes (a section is added, edited, moved or removed) and when it is published or unpublished, so it is the date to show as "last updated", or to use as a sitemap's last-modified date. publishedAt is null while the page is unpublished.

query {  page(ref: { slug: "/blog/hello" }) {    metadata {      createdAt      updatedAt      published      publishedAt    }  }}

A Directory represents a folder-like node in your content tree. It groups related pages under a shared path (for example docs/api) and can also contain nested subdirectories, letting you model your site structure in a familiar, hierarchical way. The Directories API reads and reshapes it.

Directories are useful for:

• Organising content: keep pages that belong together (like all API docs) under the same directory.

• Building navigation: use a directory’s children to render a sidebar or tree view (directories and pages).

• Querying by location: fetch all pages in a directory (pages) or traverse the hierarchy (children) starting from any directory path.

• Permissions by structure: to control a whole part of your content at once, such as everything under /blog, use a permission rule in the console. A rule matches a path pattern like /blog/** and can grant or cap access for every page that matches, including pages that already exist, whatever each page's own permissions say. See Publishing and access.

In practice, if you create pages with slugs like /docs/users and /docs/pages, they’ll naturally live under the docs directory, and docs can have its own children (subdirectories and pages) to represent your documentation structure.

type Directory implements PageReference & PageNode {  slug: String!                    # URL-friendly identifier for the directory  title: String                    # Title, when the directory is also a page  path: String!                    # Full path from root to this directory  pages: [Page!]!                  # Pages directly contained in this directory  children: DirectoryConnection!   # Child directories and pages contained within this directory  hasChildren: Boolean!            # Whether anything is filed under this directory  permissions: PagePermissions!}

Sections are the logical grouping within a page. The Sections API adds, edits and nests them in code, and the Page Editor does the same visually. They can be used to:

• Store rich text

• Hold images, as Markdown images in a text section, hosted wherever you like

• Nest and group other sections

interface Section {  id: ID!         # Unique identifier for the section  slug: String!   # URL-friendly slug for the section}

Text sections are the simplest form of Section. They have a field markdown that you can store string data in and an auto-generated plaintext field that returns the contents of markdown with any markdown formatting removed.

type TextSection implements Section {  id: ID!               # Unique identifier for the section  slug: String!         # URL-friendly slug for the section  markdown: Markdown!   # Rich markdown content of the section  plaintext: String!    # Auto-generated plain text version of the content}

Group sections allow you to structure and group other sections into more meaningful data structures.

type GroupSection implements Section {  id: ID!                 # Unique identifier for the section  slug: String!           # URL-friendly slug for the section  children: [Section!]!   # All child sections contained in this group}