Orbit MD

Gatsby

Setting up a Gatsby site

A Gatsby site needs a short content map in orbit.config.yaml, at the root of the site, next to gatsby-config.js. Orbit then edits your Markdown posts and pages through a form, and a post an editor adds is built by your template like any other.

The quickest start is the Gatsby blog in Orbit Extras — Gatsby’s official blog starter, already set up.

The content map

For a site laid out like Gatsby’s blog starter — each post a folder with an index.md and its images, rendered by src/templates/blog-post.js:

# orbit.config.yaml
assetsDir: src/images

sections:
  posts:
    files: content/blog/**/index.md
    newPage: "{slug}/index.md"
    template: src/templates/blog-post.js
  • files — the folder gatsby-source-filesystem reads, plus the pattern of your pages.
  • template — the template gatsby-node.js uses in createPages. Naming it lets editors add posts; leave it out for pages that are fixed.
  • newPage — {slug}/index.md gives each new post its own folder, as the starter does. Images uploaded for a post go beside it, as ./photo.jpg.

Without fields, Orbit works the form out from your posts. To get required fields and a date picker, list them or point at a JSON Schema — the Extras blog uses schemas/post.schema.json:

{
  "type": "object",
  "required": ["title", "date"],
  "properties": {
    "title": { "type": "string" },
    "date": { "type": "string", "format": "date-time" },
    "description": { "type": "string" }
  }
}

Dates are saved exactly as they’re written in your posts.

Site details

Gatsby keeps the site’s title, author and description in siteMetadata, inside gatsby-config.js — code editors shouldn’t touch. Move them to a JSON file and have the config read it:

// gatsby-config.js
module.exports = {
  siteMetadata: require(`./content/site.json`),
  plugins: [ /* … */ ],
}

Then list the file under data: and editors get a form for it:

data:
  - path: content/site.json
    label: Site details

Images

  • Images processed by gatsby-plugin-image — in src/images, or beside a post — are referenced by relative path, which Orbit writes for you.
  • Files in static/ are served from the site root, so an image there is written as /images/photo.jpg. Set assetsDir: static/images to use it.

MDX

If the site has gatsby-plugin-mdx, sections whose files include .mdx take MDX pages, and editors can insert the components you declare in orbit.config.yaml. The Material blog in Orbit Extras is an MDX site.

Check it

Open the site in Orbit and go to Site settings ▸ What Orbit edits: each section should list its pages and say new pages built by your template.