Blog and Changelog

Publish blog posts and release notes as Markdown files: frontmatter, drafts, images, paging, the RSS feed and renaming a post.

The blog (/blog) and the changelog (/changelog) are collections of Markdown files in your repository. Each file is a page, rendered once and served from the edge cache like the other marketing pages. There is no CMS to run; to read entries from one instead, see Content Sources.

This page is part of the Marketing documentation.

What's Where

PartLocation
Blog postsapps/web/content/blog/*.md
Changelog entriesapps/web/content/changelog/*.md
Collections, frontmatter fields, page sizeapps/web/config/content.config.ts
Pagesapps/web/pages/(marketing)/blog/, apps/web/pages/(marketing)/changelog/
Feedapps/web/routes/blog/rss.xml.ts (/blog/rss.xml)
Labels (titles, empty state, pager)apps/web/messages/<locale>/marketing.json → blog, changelog, content
Engine and page blocks@kit/content (packages/content/)

Add an Entry

Create a file; its name is its URL. apps/web/content/blog/hello-world.md is served at /blog/hello-world:

---
title: Hello world
description: One or two sentences, shown on the index, in search results and in the feed.
date: 2026-11-02
author: Ada Lovelace
---
The body is Markdown: headings, lists, tables, code blocks and callouts.
> [!TIP]
> Callouts use GitHub's syntax: NOTE, TIP, IMPORTANT, WARNING, CAUTION.

File names are lowercase words joined by hyphens (hello-world.md, not Hello World.md). Entries are listed newest first; two entries on the same date are ordered by file name.

Run pnpm dev and open /blog/hello-world to see it. Commit and deploy to publish.

Frontmatter

FieldRequiredCollectionsNotes
titleyesallThe page's <h1> and <title>
descriptionyesallIndex, <meta name="description">, feed
dateyesallISO only: 2026-11-02. Shown as written in every time zone. A datetime keeps its calendar day if quoted ("2026-11-02T23:00:00-05:00"); unquoted, YAML converts it to UTC first
imagenoallA cover from apps/web/public/, as /images/cover.webp
statusnoallpublished (default) or draft
authornoblogShown on the post and the index
versionnochangelogShown as v1.2.0 next to the date

The schema is strict: a misspelled field fails instead of being ignored. To add a field, extend the collection's schema in config/content.config.ts; the pages get it typed:

blog: {
basePath: '/blog',
schema: entrySchema.extend({
author: z.string().min(1).optional(),
readingLevel: z.enum(['beginner', 'advanced']).optional(),
}),
},

Validation

pnpm test:unit checks every file (drafts too) and fails naming the file, the field and what a valid value looks like:

Invalid blog content:
content/blog/hello-world.md: date: must be an ISO date, e.g. 2026-03-04

It also fails when an image isn't in public/. The dev server shows the same error when you open the page. vp build doesn't validate, so keep the unit tests in CI.

Drafts

Set status: draft to keep an entry off the site. Drafts are listed on the dev server only: a deployed site has no page, index row, feed item or prerendered path for them, and their content never reaches the browser bundle. Remove the line (or set published) to publish.

A future date doesn't schedule anything: the entry is published on the next deploy, with that date shown. Hold it with status: draft instead.

Paging

Indexes show pageSize entries (10 by default, in config/content.config.ts). Older entries move to /blog/page/2, /blog/page/3… with a pager under the list; /blog is page 1, so /blog/page/1 is a 404, as are pages past the last one.

The Feed

/blog/rss.xml is an RSS 2.0 feed of published posts (title, description, date and link; not the full post). Its links use SITE_URL, never the request's host, so set SITE_URL for every deployment (Environment variables). The blog index advertises it to feed readers.

Renaming an Entry

The file name is the URL, so renaming hello-world.md breaks links to /blog/hello-world. Add a permanent redirect in apps/web/void.config.ts:

routing: {
isr: true,
redirects: {
'/blog/hello-world': { to: '/blog/hello-again', status: 301 },
'/*/blog/hello-world': { to: '/:splat/blog/hello-again', status: 301 },
},
},

The second rule covers locale-prefixed URLs (/it/blog/hello-world) once you have more than one locale.

Raw HTML and Security

Markdown may contain raw HTML, and it is rendered as written, <script> included. Content pages are served without a Content Security Policy to visitors without cookies (that's what lets the edge cache share them; see Caching), so nothing would block it. Review content pull requests like code: anyone who can merge a Markdown file can run script on your domain.

Frontmatter is public: never put secrets or private notes in it.

Translations

One file serves every locale: once you add Italian (it), /it/blog/hello-world shows the same body with the site's chrome (labels, dates, navigation) in Italian. Labels live in messages/<locale>/marketing.json.

Design

Entry pages compose small blocks from @kit/content/react (EntryLayout, EntryTitle, EntryBody…), so you can restyle or reorder one in pages/(marketing)/blog/ without editing the package. Index pages render BlogIndex and ChangelogIndex from @kit/content/ui (built from EntryGrid, EntryTimeline, Pager…): to restyle one, compose your own index from @kit/content/react blocks, or edit the package. Their pager labels are the kit namespace content. Body typography is .content-body in apps/web/styles/makerkit.css.

Add a Collection

To add another collection, say /guides:

  1. Add it to collections in config/content.config.ts (basePath: '/guides', a schema).
  2. Export it from config/content.server.ts, like blog.
  3. Copy pages/(marketing)/changelog/ to pages/(marketing)/guides/ and point it at the new collection; add its labels under marketing.guides (like marketing.changelog) and pass namespace="marketing.guides" to ChangelogIndex (@kit/content/ui), or compose your own index from @kit/content/react blocks. The unit tests fail until [slug].tsx exists under the basePath.
  4. Add its labels to messages/<locale>/marketing.json and a link in config/marketing-navigation.config.ts.
  5. Put its Markdown in apps/web/content/guides/.

Next: Help Docs →