Overall flow

Space content on GitBook is versioned in a similar way to Git, each change result in a complete snapshot of the content (called Revision). Each revision is linked to the previous content snapshot: its parent.

Each space contains a reference to the latest snapshot to use (primary revision). Drafts in a space also contain references to revisions (current content and ancestor).

Revisions

A revision is a snapshot of the space content at a specific point in time. It contains everything used to display a space:

• ​Variants​

• ​Pages for each variant

• ​Assets​

type Revision {
    uid: string;
    variants: Variant[];
    assets: Asset[];
}

Variants

Variants are alternative sets of pages in a revision. You can create variants from the UI to document multiple languages or multiple versions of an API.

type Variant = {
    uid: string;
    ref: string;
    page: Page;
}

Pages

Each variant starts with a root page, the tree of pages represent the table of content visible to the end user. GitBook has 3 kind of pages:

• Document pages

• Group (only possible under the root page)

• External links

type Page = PageDocument | PageGroup | PageLink;
​
type PageDocument = {
    uid: string;
    title: string;
    path: string;
    pages: Page[];
    document: Document;
}
​
type PageGroup = {
    uid: string;
    title: string;
    pages: Page[];
}
​
type PageLink = {
    uid: string;
    title: string;
    href: string;
}

Documents

Documents is the lowest primitives of content, it defines the inner content of a page. Documents can be obtained (or set) from the API using our JSON format or Markdown (?format=markdown).

Assets

Assets represent binary files that are stored with the text content, documents can reference assets to include images or files.

type Asset = {
    uid: string;
    name: string;
    contentType: string;
    downloadURL: string;
};