Managing Blog Posts in next-dev-portfolio

All blog posts in next-dev-portfolio live in a single JSON file: src/data/collections/posts/posts.json. The file is a keyed object where each top-level key is the post’s slug, and each value is a fully typed post record validated by a Zod schema at build time. Adding a new post is as simple as appending a new key-value pair to that object and running a rebuild.

File Location

src/data/collections/posts/posts.json

Data Structure

The top-level object is a map of slug → post. This makes look-ups O(1) and keeps the dynamic route /blog/[slug] simple — the renderer reads the key that matches the URL parameter.

{
  "your-post-slug": { ... },
  "another-post-slug": { ... }
}

Required Fields

Every post record must include all of the following fields. The Zod schema will reject the build if any required field is missing or has the wrong type.

Field	Type	Description
`id`	`string`	Must match the top-level key exactly
`title`	`string`	Display title shown in listings and at the top of the post
`dek`	`string`	One-sentence sub-headline summarising the post’s argument
`date`	`string`	Publication date in `YYYY-MM-DD` format
`readingTime`	`string`	Human-readable estimate, e.g. `"9 min"`
`tags`	`string[]`	Array of lowercase tag strings used for filtering
`body`	`string`	Full post content in Markdown (GitHub-flavored)

Optional Fields

Field	Type	Description
`image`	`object`	Cover image — requires `url` and `alt` sub-fields

The `body` Field

The body field accepts GitHub-flavored Markdown rendered via remark-gfm. You can use all standard GFM features inside it:

Headings (##, ###)
Fenced code blocks with language tags
Tables
Task lists
Bold, italic, inline code, and blockquotes

Write the Markdown as a JSON string, using \n for newlines and \n\n for paragraph breaks.

"body": "## The quiet failure mode\n\nMost content platforms fail the same way: a free-form blob field...\n\n```typescript\nconst schema = z.object({ title: z.string() });\n```"

The `image` Object

When provided, the cover image object requires two sub-fields:

Sub-field	Description
`url`	Absolute URL to the image. Unsplash works well — append `?w=1600&q=80` for optimal delivery.
`alt`	Descriptive alt text for screen readers and SEO

"image": {
  "url": "https://images.unsplash.com/photo-1516321318423-f06f85e504b3?w=1600&q=80",
  "alt": "Laptop screen showing structured document markup"
}

Use Unsplash source URLs and always append ?w=1600&q=80 to serve a web-optimized 1600 px wide JPEG. This keeps page weight low while preserving sharpness on retina displays.

How Posts Are Displayed

Posts surface in two places in the default layout:

Blog list page — /blog

The posts-list section on src/data/pages/blog.json renders every post in reverse-chronological order. Tags are shown as clickable filter chips.

Home page — recent posts

The recent-posts section on src/data/pages/home.json shows the most recent N posts. Control the count with the limit field in that section’s data object.

To change how many posts appear in the home page teaser, open src/data/pages/home.json and update the limit value in the recent-posts section:

{
  "id": "home-posts-1",
  "type": "recent-posts",
  "data": {
    "label": "Writing",
    "title": "Latest notes",
    "limit": 4,
    "items": { "$ref": "../collections/posts/posts.json" }
  }
}

Dynamic Route

Every post is accessible at /blog/[slug], where [slug] is the top-level key in posts.json. The template file at src/data/pages/blog/[slug].json configures the post-detail section that renders the full article body.

The slug key and the id field must always match. Mismatched values will cause the detail page to fail its schema validation at build time.

Adding a New Post

Open posts.json

Open src/data/collections/posts/posts.json in your editor.

Append a new entry

Copy an existing post object, paste it as a new key-value pair at the end of the top-level object, and update every field. Choose a slug that is URL-safe: lowercase letters, numbers, and hyphens only.

{
  "existing-post-slug": { ... },
  "my-new-post-slug": {
    "id": "my-new-post-slug",
    "title": "Your post title here",
    "dek": "A single sentence that captures the post's core argument.",
    "date": "2026-06-01",
    "readingTime": "7 min",
    "tags": ["tag-one", "tag-two"],
    "body": "## Introduction\n\nYour post body in Markdown goes here.",
    "image": {
      "url": "https://images.unsplash.com/photo-XXXXXXXXXXXXXXXXXX?w=1600&q=80",
      "alt": "Descriptive alt text for the cover image"
    }
  }
}

Rebuild the site

npm run build

The build pipeline validates every post against the Zod schema. If a required field is missing or a type is wrong, you’ll see a descriptive error pointing to the exact field.

Removing a Post

Delete the entire key-value pair from posts.json, then rebuild. The post will no longer appear in listings or be accessible at its /blog/[slug] URL.

Removing a post that is linked from another page (for example, a hand-crafted link in a cta-band section) will produce a broken link. Search for the slug across your src/data/pages/ files before deleting.

Complete Post Example

{
  "schema-driven-content": {
    "id": "schema-driven-content",
    "title": "Schema-driven content is the missing layer",
    "dek": "Why treating page sections as typed contracts beats free-form CMS blobs for multi-tenant sites.",
    "date": "2026-03-12",
    "readingTime": "9 min",
    "tags": ["schemas", "cms", "content-infra"],
    "body": "## The quiet failure mode\n\nMost content platforms fail the same way: the editor UI drifts from the renderer, and nobody notices until a publish breaks production.\n\n## Contracts over conventions\n\nSchema-driven content means every section, collection item, and form submission has a Zod contract shared by Studio, CI, and runtime.\n\n## The payoff\n\nYou trade a little authoring friction for operational calm. Publish errors become schema errors you can fix before merge.",
    "image": {
      "url": "https://images.unsplash.com/photo-1516321318423-f06f85e504b3?w=1600&q=80",
      "alt": "Laptop showing structured documents on a dark background"
    }
  }
}

Get Started

Content

Studio

Customization

Advanced

File Location

Data Structure

Required Fields

Optional Fields

The `body` Field

The `image` Object

How Posts Are Displayed

Blog list page — /blog

Home page — recent posts

Dynamic Route

Adding a New Post

Removing a Post

Complete Post Example

​File Location

​Data Structure

​Required Fields

​Optional Fields

​The body Field

​The image Object

​How Posts Are Displayed

Blog list page — /blog

Home page — recent posts

​Dynamic Route

​Adding a New Post

​Removing a Post

​Complete Post Example

File Location

Data Structure

Required Fields

Optional Fields

The `body` Field

The `image` Object

How Posts Are Displayed

Dynamic Route

Adding a New Post

Removing a Post

Complete Post Example