Directories API

Directories organise your pages into a tree, the way folders organise files. A page's slug says where it lives: /docs/api/pages lives in the /docs/api directory, which lives in /docs. Pages introduces directories alongside pages and sections.

You rarely create a directory yourself. Creating a page creates every directory above it, so creating /docs/api/pages gives you /docs and /docs/api as well.

A node can be both a page and a directory. /blog can be your blog's index page and also hold /blog/hello beneath it. A filesystem would not allow that; here it is a normal shape, and the API is built around it.

A Directory is one folder in your content tree. Read one to build navigation, such as a documentation sidebar or a site map, or to list everything filed under a path.

type Directory implements PageReference & PageNode {  slug: String!  path: String!  title: String                    # Set when the directory is also a page  hasChildren: Boolean!            # Whether anything sits directly inside it  children: DirectoryConnection!   # The pages and directories directly inside it  pages: [Page!]!                  # The pages directly inside it  metadata: PageMetadata  permissions: PagePermissions!}

Three queries reach it:

• directories returns the directories at the top level.
• directory(path: String!) returns one directory by its path, or null.
• pagesNode(ref: SlugOrId!) returns whatever is at a slug or ID, page or directory, as a PageNode.

Walk down with children. Each child is a PageNode, the interface pages and directories share, so one selection reads the title and hasChildren of every child. Ask for page-only fields with ... on Page:

query {  directory(path: "/docs") {    children {      edges {        node {          slug          title          hasChildren          ... on Page {            id          }        }      }    }  }}

Use hasChildren to tell a node you can open from a leaf, for example to draw an expand arrow in a sidebar. It is true for a page that has pages beneath it, too.

A page at the directory's own path is listed first. If /blog is a page as well as a directory, directory(path: "/blog") lists the /blog page itself at the top of children and pages, followed by what is inside. That is how an index page shows up alongside its posts. Skip it if you only want what is inside.

Only nodes you can read are listed. A child you have no read permission on is left out rather than failing the whole query.

Create an empty directory with createDirectory.

mutation {  createDirectory(path: "/docs/guides") {    path  }}

It creates any directories above it too, and needs write permission where the new directory will live. It is safe to repeat: if the directory already exists, you get it back unchanged.

Create one yourself when you want it to exist before it has any pages.

Delete a directory, and optionally everything inside it, with deleteDirectory.

mutation {  deleteDirectory(ref: { slug: "/docs/old" }, recursive: false) {    deleted    pageCount    directoryCount  }}

Without recursive, only an empty directory is deleted. If anything is inside, nothing is deleted: deleted is false, and pageCount and directoryCount say what is in the way.

With recursive: true it deletes the directory and everything beneath it, at any depth, and the counts say what was removed. This cannot be undone.

Start a directory afresh with clearDirectory, which keeps the directory and its permissions.

mutation {  clearDirectory(ref: { slug: "/docs/old" }) {    pageCount    directoryCount  }}

clearDirectory deletes everything inside a directory but keeps the directory, with its permissions. Use it rather than deleting and recreating a directory whose permissions you want to keep.

deletePage deletes a page's content, never what is filed beneath it. If anything is beneath it, the node stays as a directory and deletePage returns false. To remove it and everything under it, use deleteDirectory with recursive: true.

Pages in a directory keep the order you give them. A new page goes at the end. To move one, give its slug and its new position, counting from 0:

mutation {  movePage(ref: { slug: "/docs/introduction" }, to: { index: 0 }) {    slug  }}

movePage reorders a page within its own directory. Refer to the page by slug: an ID is not accepted here. To move a page to a different directory, create it at the new slug and delete the old one.

That order is also what Page.next and Page.previous follow: the page or directory before and after this one in its directory, or null at either end. They are what a "previous / next" footer on a documentation site is built from:

query {  page(ref: { slug: "/docs/introduction" }) {    previous {      ... on Page {        slug        title      }    }    next {      ... on Page {        slug        title      }    }  }}

Each is a DirectoryChild, which is a Page or a Directory, so select the fields you need on each type.