Documents

A document contains a site's content, like a page, a blog post or a product in a structured format.

Documents are stored in /documents/, one file each, as .json, .yml or .md. A document's location in /documents/ determines its live URL.

// /documents/about.json
{
  "_id": "9fe69db2-7172-464f-ba77-34ab7b101442",
  "_type": "Page",
  "title": "About us",
  "hero": { 
    "_type": "Hero", 
    "heading": "Join our mission."
  },
  "footer": { 
    "_ref": "79ead044-d4a6-4ffc-b04d-9fadd0e79c73" 
  }
}

Anatomy

A document is an object. Properties that start with _ are reserved, all others hold the content.

• _type: the schema the object follows. Every object needs one, except a reference.
• _id: the document's unique id. It's added automatically when the file has none.
• _ref: a link to another document, by its _id.
• _slug: the document's route, only available at build time derived from its path.

Each property holds either a string, number, boolean, null, an object or a list of objects. An object inside a document is one of two kinds:

• Fragment: an object with a _type, like hero above. It lives inside the document and isn't stored on its own.
• Reference: an object with only a _ref, like footer above. It points at another document.

All three file formats decode to the same object. JSON and YAML map one to one. In markdown, the frontmatter holds properties and the body is added into a children array of fragments (p, h1-h6, ul/ol, img, a, code). Tags in the body, like <Video src="/media/demo.mp4" />, become fragments too.

Example

Different representations of the same blog post.

---
_type: Post
title: Hello
---

# Welcome

This is **my** first post.

<Video src="/media/demo.mp4" />

_type: Post
title: Hello
children:
  - _type: h1
    children:
      - { _type: text, text: Welcome }
  - _type: p
    children:
      - { _type: text, text: "This is " }
      - { _type: text, text: my, bold: true }
      - { _type: text, text: " first post." }
  - { _type: Video, src: /media/demo.mp4 }

{
  "_type": "Post",
  "title": "Hello",
  "children": [
    { "_type": "h1", "children": [{ "_type": "text", "text": "Welcome" }] },
    { "_type": "p", "children": [
      { "_type": "text", "text": "This is " },
      { "_type": "text", "text": "my", "bold": true },
      { "_type": "text", "text": " first post." }
    ] },
    { "_type": "Video", "src": "/media/demo.mp4" }
  ]
}