# Blog and Changelog

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/marketing/blog-and-changelog*

---

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](./content-sources).

This page is part of the [Marketing documentation](./overview).

## What's Where

| Part | Location |
|---|---|
| Blog posts | `apps/web/content/blog/*.md` |
| Changelog entries | `apps/web/content/changelog/*.md` |
| Collections, frontmatter fields, page size | `apps/web/config/content.config.ts` |
| Pages | `apps/web/pages/(marketing)/blog/`, `apps/web/pages/(marketing)/changelog/` |
| Feed | `apps/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`:

```md
---
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

| Field | Required | Collections | Notes |
|---|---|---|---|
| `title` | yes | all | The page's `<h1>` and `<title>` |
| `description` | yes | all | Index, `<meta name="description">`, feed |
| `date` | yes | all | ISO 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 |
| `image` | no | all | A cover from `apps/web/public/`, as `/images/cover.webp` |
| `status` | no | all | `published` (default) or `draft` |
| `author` | no | blog | Shown on the post and the index |
| `version` | no | changelog | Shown 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:

```ts
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:

```text
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](../configuration/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`:

```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](./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 →](./help-docs)
