---
title: Drafts and publishing
description: A working copy for any collection's entries, published now or at a set time, with every version kept.
section: Data
order: 7
---

# Drafts and publishing

A working copy for any collection's entries, published now or at a set time, with every version kept.

Any collection can work like a CMS. Changes are saved as a draft that only editors see, and go live when you publish them, now or at a time you set. The collection's own records are what is published, so everything that reads them (the REST API, sync, rules, your app) keeps seeing only published content, with nothing to change.

This comes with the content plugin (`sluurp plugin add content`). To make a collection content, name it in `/api/content`, or in a migration:

```json title="migrations/V1__init.json"
{ "content": { "collections": ["articles"], "locales": ["en", "fr"] } }
```

Features include:

- Drafts, scheduled publishing, and every published version kept
- Addresses, languages, translations and search metadata on each entry
- Previews of a draft on the real page, and links to share them
- Bodies in blocks, a media library, and imports from Markdown, WordPress and Strapi
- Roles for writers, editors and publishers, and a ready-made editor

## In the admin

Open a content collection in the admin, and its entries are edited as drafts. The sheet shows where an entry stands, its fields, and a **Publishing** section with:

- its address (made from the title if left empty);
- its language;
- its title and description for search and sharing;
- a time to publish it at.

**Save draft** keeps the working copy. **Publish** puts it live now, or schedules it when a time is set. **Discard the draft**, in the sheet's menu, drops the changes. The collection lists its drafts, including entries never published, above its records.

## Save a draft

```http title="HTTP"
PUT /api/collections/articles/records/new/draft
{ "data": { "title": "Hello", "body": "First version" } }
```

`new` makes a new entry, and the answer gives its id. To change a published entry, save a draft with its id: only the fields you send change when it's published. Save as often as you like; nobody else sees it.

## Read a draft

```http title="HTTP"
GET /api/collections/articles/records/{id}/draft
```

This answers the working copy (the published fields with the draft's on top), the published record, and where the entry stands:

| State | Means |
|---|---|
| `draft` | Never published yet |
| `published` | Live, with no changes waiting |
| `changed` | Live, with a draft of changes waiting |
| `scheduled` | A draft set to be published at a time |

To list a collection's drafts, the latest changed first, call `GET /api/collections/articles/drafts`.

## Publish

```http title="HTTP"
POST /api/collections/articles/records/{id}/publish
POST /api/collections/articles/records/{id}/publish   { "at": "2026-11-01T09:00:00+01:00" }
```

Without a time, the draft goes live at once. With a time in the future, it is scheduled, and published within a minute of that time. Publishing is an ordinary create or update, so the collection's rules, hooks and realtime updates apply as they do to any save.

To drop a draft, call `DELETE /api/collections/articles/records/{id}/draft`. The published version doesn't change.

## Content fields

When a collection becomes content, Sluurp adds and keeps a few fields for it. Like everything Sluurp manages, their names start with `_`:

| Field | What it holds |
|---|---|
| `_slug` | Its address, made from its title (`Héllo Wörld` → `hello-world`) and kept unique in its language (`hello-world-2`) |
| `_seo` | A title, a description and an image for search and sharing |
| `_locale` | Its language: the site's first, if not given |
| `_of` | The entry it translates, for the same content in several languages |
| `_published` | When it was first published |

Over HTTP:

```http title="HTTP"
PUT /api/content   { "collections": ["articles"], "locales": ["en", "fr"] }
```

Your own fields stay as they are. To find a published entry by its address, as the collection's rules let the caller see it:

```http title="HTTP"
GET /api/collections/articles/slug/hello-world?locale=fr
```

## Show it on a site

The content plugin gives a page what is published. Add it once; it brings the blocks plugin, which draws a body:

```sh title="Terminal"
sluurp plugin add content
```

It then gives a React page what is published, as hooks:

```tsx title="app.tsx"
import { useEntries, useEntry } from "@sluurp-plugins/content/client/index.ts";

const posts = useEntries("articles", { locale: "fr", perPage: 10 });
const post = useEntry("articles", "hello-world");
```

Both read the delivery API, which answers only with published entries, as the collection's rules let the reader see them. The browser keeps each answer and asks again cheaply.

```http title="HTTP"
GET /api/content/articles?locale=fr&page=1&perPage=10
GET /api/content/articles/hello-world?locale=fr
```

## For search engines

`useEntries` and `useEntry` fill a page in the browser. A server page sends it finished instead, which is what search engines and link previews read. To render an entry on the server, await it in a page at its address:

```tsx title="routes/blog/[slug].tsx"
import { getEntry } from "@sluurp-plugins/content/client/index.ts";
import { Body } from "../../components/body.tsx"; // "use client"; export { Body } from the plugin's client/body.tsx

export default async function Post({ params }) {
  const post = await getEntry("articles", params.slug);
  return <article><h1>{post?.title}</h1><Body blocks={post?.body} /></article>;
}
```

Once the collection's address is set (see [Previews](#previews); `/blog/{slug}` here), Sluurp adds the rest:

- the page's head gets the entry's title, description, share picture, canonical address, and its other languages (`hreflang`);
- `/sitemap.xml` lists every published entry, in every language;
- `/blog/feed.xml` is an Atom feed of the latest entries.

An address can hold the language too: `/{locale}/blog/{slug}`.

## Translations

With more than one language, an entry's sheet shows its **Languages**: each translation, published or drafted, and **Translate to …** for each language it isn't in yet. That starts a draft in the new language, linked to the original (`_of`) and copied from it to write over, with the original kept in view. Publishing the draft makes it one of the entry's languages, with `hreflang` links between them on the site.

```http title="HTTP"
GET  /api/collections/articles/records/{id}/translations
POST /api/collections/articles/records/{id}/translate   { "locale": "fr" }
```

Agents translate too: `save_draft` with `entry: "new"`, `_locale` and `_of`, and the fields written in the new language.

## Import entries

**Import**, on a content collection in the admin, brings entries in from elsewhere:

| From | What's kept |
|---|---|
| Markdown files | Frontmatter `title`, `slug` (else the file name), `date`, `description`, `tags`, `lang`; a first `# Heading` as the title |
| A WordPress export (WXR `.xml`) | Posts' titles, addresses, publication dates, excerpts, tags and categories |
| Strapi entries (`.json`) | `title`, `slug`, `publishedAt`, `locale`, `description`, and any field the collection has by the same name; Markdown or Strapi blocks as the body |

Bodies become blocks in a `json` body field, or text in a text one. Entries are published with their own dates, or brought in as drafts. Pictures stay at the addresses they had.

```http title="HTTP"
POST /api/content/articles/import   { "format": "markdown", "files": [{ "name": "hello.md", "text": "…" }] }
POST /api/content/articles/import   { "format": "wordpress", "text": "<rss …>", "drafts": true }
```

Sluurp reads an export's XML with document type definitions refused: no entities are expanded, and nothing outside the file is ever read.

## Example: a blog

The [`blog`](https://github.com/SluurpHQ/examples/tree/main/blog) example is a blog built only on this: posts in English and French with their translations linked, tags, an Atom feed per language and a sitemap. One migration holds the collection, the content model and sample posts:

```json title="migrations/V1__init.json"
{
  "collections": [{ "name": "articles", "schema": [{ "name": "title", "type": "text" }, { "name": "body", "type": "json" }], "rules": { "list": "", "view": "" } }],
  "content": { "collections": ["articles"], "locales": ["en", "fr"], "previews": { "articles": "/{locale}/{slug}" } }
}
```

Its pages are `routes/[locale]/index.tsx` (the list) and `routes/[locale]/[slug].tsx` (a post).

## Previews

To say where a collection's entries are shown on the site:

```http title="HTTP"
PUT /api/content   { "previews": { "articles": "/blog/{slug}" } }
```

The editor then has a **Preview** section. **Show preview** opens the entry's page beside the fields, with the draft in it, and the page changes as you type. **Copy preview link** gives a link anyone can open to see the draft for a week, without signing in.

A page opened from a preview link has `?preview=` in its address, and `useEntry` reads the draft instead of what is published. Nothing else on the page needs to change.

## Bodies in blocks

Give a content collection a `json` field called `body` (or `content`, or `blocks`), and the admin edits it in blocks, as a page is: headings, lists, quotes, code, pictures and more, with `/` to choose. A site renders it with `Body`, plainly on the server and as the Blocks plugin draws it in the browser:

```tsx title="app.tsx"
import { Body, useEntry } from "@sluurp-plugins/content/client/index.ts";

const post = useEntry("articles", "hello-world");
<article><Body blocks={post?.body} /></article>
```

## Media

**Media**, in the admin, holds the project's pictures and files. Drop them on the page or choose them with **Upload**. Open one to describe it for people who can't see it, add a caption or a folder, copy its address, or delete it. An entry's **Picture when shared** is chosen from here.

Anyone can read them, as with any site's pictures. Each has its own address, and is resized on the way out:

```html
<img src="/api/files/_media/{id}/file?w=800" alt="…">
```

The library is the `_media` collection, so the records API lists and searches it like any other: `GET /api/collections/_media/records`.

## React to publishing

Publishing an entry emits `content.published`, and sending one for review emits `content.review`, as [events](/docs/hooks-and-events). An agent can act on them, to rebuild a static site, clear a cache, or call any webhook:

```ts title="agents/deploy.ts"
export const watch = { event: "content.published" };

export async function act({ event }) {
  await fetch("https://api.example.com/deploy-hook", { method: "POST", body: JSON.stringify(event.data) });
}
```

`event.data` has the `collection`, the entry's `id`, `slug`, `locale`, its `address` on the site, and who published it (`by`). The admin's sidebar counts the drafts waiting for review beside their collection.

## Coding agents

[Coding agents](/docs/mcp) connected to Sluurp read and write content too:

| Tool | Does |
|---|---|
| `content_model` | The content collections and their fields, the languages, and where entries are shown |
| `list_entries`, `read_entry` | Published entries, and one by id or address with its draft |
| `list_drafts`, `list_media` | The drafts waiting, and the media library's pictures |
| `save_draft` | A draft of a new entry or of changes, sent for review with `review: true` |

An agent writes as a writer named `agent`, and each draft it saves can be undone in **AI › Agents**. It never changes a draft a person wrote, and never publishes: a person reviews its drafts and publishes them. A read-only key reads and writes nothing.

## Versions

A collection keeps its history from its first draft. Each published version is in the entry's history (`GET /api/collections/articles/records/{id}/history`), to compare and go back to.

## Roles

Give people one of three roles, and drafts and publishing are theirs as well as superusers':

| Role | May |
|---|---|
| `writer` | Write new entries and change their own drafts, send them for review, add pictures to Media |
| `editor` | All a writer may, on anyone's drafts, and discard them |
| `publisher` | All an editor may, and publish or schedule |

A draft keeps its writer when an editor changes it. A writer sends a draft for review by saving it with `"review": true`, and it shows as `review` until it's published.

To build an app's own editor, use `drafts`:

```tsx title="app.tsx"
import { drafts } from "@sluurp-plugins/content/client/index.ts";

const articles = drafts(sluurp, "articles");
const { id } = await articles.save("new", { title: "Hello" });
await articles.save(id, {}, { review: true });
await articles.publish(id);
```

Each call is allowed or refused by the signed-in person's role, and `articles.role()` says which they have.

For a whole editorial screen, ready made:

```tsx title="app.tsx"
import { ContentEditor } from "@sluurp-plugins/content/client/editor.tsx";

<ContentEditor client={sluurp} collection="articles" />
```

It lists what is in review, the drafts and what is published, and opens an entry with its fields (a body in blocks), its address, language and description. Writers get **Send for review**, publishers **Publish**, and editors and publishers **Discard**.
