DocsData

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:

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

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

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:

StateMeans
draftNever published yet
publishedLive, with no changes waiting
changedLive, with a draft of changes waiting
scheduledA 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

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 _:

FieldWhat it holds
_slugIts address, made from its title (Héllo Wörld → hello-world) and kept unique in its language (hello-world-2)
_seoA title, a description and an image for search and sharing
_localeIts language: the site’s first, if not given
_ofThe entry it translates, for the same content in several languages
_publishedWhen it was first published

Over 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:

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:

sluurp plugin add content

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

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.

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:

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; /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.

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:

FromWhat’s kept
Markdown filesFrontmatter 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.

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

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:

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:

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:

<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. An agent can act on them, to rebuild a static site, clear a cache, or call any webhook:

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 connected to Sluurp read and write content too:

ToolDoes
content_modelThe content collections and their fields, the languages, and where entries are shown
list_entries, read_entryPublished entries, and one by id or address with its draft
list_drafts, list_mediaThe drafts waiting, and the media library’s pictures
save_draftA 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’:

RoleMay
writerWrite new entries and change their own drafts, send them for review, add pictures to Media
editorAll a writer may, on anyone’s drafts, and discard them
publisherAll 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:

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:

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.

View as Markdown