Custom Collections

A custom collection is your own content type. Where SpiderPublish gives you pages, blog posts, and docs out of the box, a collection lets you (or your agent) invent a new type — case studies, team members, FAQs, products, testimonials — declare the fields it has, fill it with rows, and render each row as a real page with its own URL and SEO. The agent designs the schema and writes the content, in one session.

When to use a collection

Reach for a collection when a plain page or blog post doesn't fit: you have structured, repeatable content — many items that share the same shape — and you want them authored in bulk and rendered as a list and detail. A "Case Studies" section, a staff directory, a product catalog, a FAQ.

How it works

There are two pieces:

A collection is the definition. It has a name (slug), a label, a schema (the list

of fields every row shares), and a switch for whether it's public.

A record is one row. It has its own slug, the field values you defined, SEO fields

(title, description, social image), and a status (draft, published, or archived).

Every published record is a first-class page. It gets a pretty URL — /your-collection/the-record — and you write its body in whichever format you like: page blocks, rich text, Markdown, or HTML.

Build one with an agent

The flow is: define → fill → publish → expose → render → deploy.

Define the collection. Tell your agent the fields you want. For a case study that might

be a title, the client name, a summary, and a logo. The agent declares them once as the schema. Each field has a type — one of: text, number, bool (yes/no), select (a fixed list of options), date, richtext (a formatted body), media (an image or file), relationship (a link to another record), or blocks (page sections). Plain words like "string" or "image" aren't types — use text and media.

Fill it with records. The agent can create rows one at a time, or bulk-create up to 100

in a single batch. Every row starts as a draft. If a row includes a field you didn't declare, the whole batch is rejected with a clear error — nothing is silently dropped, so what you see is exactly what's stored.

Publish the rows you want live. Publishing is a two-step, confirmed action (the agent

previews the change, then confirms it) — the same safety model as everything else in SpiderPublish. Draft rows stay hidden.

Make the collection public. A collection is private until you flip it on. Once public,

its published rows are available to your site.

Render it. Drop a dynamic component on a page, pointed at your collection — it

works exactly like the built-in "latest posts" style components, looping over your rows. Individual records also render automatically at their own pretty URL.

Deploy. Publishing makes a row live in your content store; a deploy makes it live on the

site. See Safe Publishing.

Relationships

Records can link to each other, or to your posts and authors — a case study can point at its author, a product at its category. When your agent reads a record, it can ask for the linked item to be filled in automatically. Links are looked up efficiently in a single step, so a list of a hundred related records stays fast.

Reading a wide collection efficiently

Listing records returns every field each record declares. On a collection with a handful of fields that's exactly what you want. On a wide one — say fifty fields per record — a single page of results runs to tens of thousands of characters, most of them fields your agent never asked about, which is enough to crowd out an agent's working memory.

Tell your agent to request only the fields it needs. It narrows the call with a fields list (just the name and the install command, say), and the response still carries the essentials — slug, status, publish date, SEO — while dropping the rest of the data. Pair that with a page size to bound how many records come back at once.

Two details worth knowing: naming a field that doesn't exist simply leaves it out rather than failing the whole request (narrowing a list should never be riskier than not narrowing it), and this is separate from asking for YAML output — that changes the format, not which fields are in it.

Good to know

Names use hyphens, not underscores — case-studies, not case_studies.
Unknown fields are rejected, not ignored. Declare every field you intend to store.
A rich-text field wants rich text, not raw HTML. If your agent pastes raw <div> HTML

into a richtext field it shows up as literal text on the page. For a formatted body, author it as normal rich text (or Markdown); use a plain text field for simple strings.

A "blocks" field holds page sections (hero, features, call-to-action, and so on) — the

same building blocks as a page, not free-form data.

Publishing is not the same as deploying. A published row is live in your store; the site

reflects it after a deploy.

Deleting cascades and is confirmed. Removing a collection removes all its rows, behind

the same preview-then-confirm gate.

Plans include limits on how many collections and records you can create; you'll get a

clear message if you reach your plan's cap.