Gatsby Docs

Where posts live

Create a new folder under content/posts. The folder name is only for your filesystem organisation; the public URL comes from the slug (see below).
Inside that folder, add index.mdx with YAML frontmatter at the top, then your article body.

Example layout:


content/posts/
  my-new-article/
    index.mdx
    optional-banner.jpg

Frontmatter

Put frontmatter between --- lines at the very start of index.mdx.

Required

title — Post headline.
date — Publish date as YYYY-MM-DD (e.g. 2026-03-19).

Optional

description — Short summary for SEO and listings. If omitted, the theme derives an excerpt from the body.
tags — List of tags. Tag pages exist at /tags/<tag-slug>/. This site’s navigation highlights Technical, Chess, and Photography; use those (and others) consistently so readers can browse by topic.
banner — Hero image path relative to the post folder, e.g. ./banner.jpg. If omitted, the default site image from siteMetadata in gatsby-config.ts is used.
slug — Custom URL path, e.g. slug: "/my-custom-url". If omitted, the theme derives a slug (typically from the folder or title).
canonicalUrl — Full URL if this post was originally published elsewhere.
defer — Set to true to opt into Deferred Static Generation (build-time optimisation for rarely visited pages).

Minimal example


---
title: "Your post title"
date: 2026-03-19
---

Fuller example


---
title: "Your post title"
date: 2026-03-19
description: "One or two sentences for previews and search."
tags:
  - Technical
  - Security
banner: ./banner.jpg
slug: "/optional-custom-path"
---

Writing the body

Below the closing ---, write normal Markdown:

Headings with #, ##, ###
Bold, italic, lists, links [text](url)
Code fences with a language tag:


```ts
const example = "syntax highlighting"
```

Put images in the same folder as index.mdx and reference them with relative paths, or use the banner field for the post header image.

Local preview

Install dependencies once with bun install. From the project root:


bun dev

(bun run develop is equivalent — both run gatsby develop from package.json.)

Open the local URL Gatsby prints (usually http://localhost:8000). New and edited MDX files are picked up while the dev server runs.

To match production output locally, use bun run build then bun run serve.

Publishing flow

Posts appear on the home page (latest posts) and the Blog section. After you commit changes, your host runs the build script (same as bun run build locally); no separate “publish” step inside the repo beyond merge/deploy.

Static pages (not blog posts)

For standalone pages like About, use content/pages/<folder>/index.mdx with at least title and usually slug (e.g. slug: "/about"). Link new pages from navigation in gatsby-config.ts if they should appear in the site header.