English for Storyblok CMS Developers
Vocabulary for developers integrating Storyblok — the visual editor, bloks, content types, and the story tree — for teams discussing headless CMS workflows in English.
Storyblok is a headless CMS built around a visual, component-based editor that lets non-technical editors compose pages from developer-defined building blocks, while the content itself is delivered as JSON through an API. Its vocabulary mixes CMS terms with its own naming — “bloks,” “stories,” “the story tree” — that don’t map one-to-one onto other headless CMS tools. If your team integrates Storyblok into a frontend, here’s the English you’ll need for content-modeling and editor-handoff conversations.
Content Modeling
Blok — Storyblok’s term for a reusable, nestable content component (deliberately spelled without the “c”), defined once by a developer and then composed freely by editors.
“We built a Hero blok and a Testimonial blok — editors can now stack and reorder them on any page without touching code.”
Content type / component schema — the developer-defined structure of fields (text, richtext, image, nested bloks) that a blok exposes to the editor. “Before adding a new field to the schema, check whether it’s already covered by an existing blok — we don’t want three near-identical hero variants.”
Nestable blok — a blok that can be placed inside another blok’s field, enabling composable page layouts (a “Grid” blok containing several “Card” bloks, for example).
“The layout is just nested bloks — a Grid blok whose columns field accepts any number of Card bloks, so editors build the page visually.”
The Visual Editor
Visual editor — Storyblok’s live, WYSIWYG-style editing interface where content editors see and click directly on the rendered page to edit the underlying bloks.
“Editors don’t touch JSON or a raw form — they click directly on the hero section in the visual editor and it opens the matching blok’s fields.”
Story — Storyblok’s term for a single content entry (a page, or a reusable piece of content), stored as a tree of bloks and organized in folders.
“Each landing page is its own story in Storyblok — duplicating one and swapping the hero copy is the fastest way to spin up a new campaign page.”
Story tree — the hierarchical folder structure of stories within a Storyblok space, mirroring how content is organized for editors.
“We’re restructuring the story tree so marketing pages and blog posts live in separate folders — right now everything’s flat, which makes permissions hard to manage.”
Preview mode — a draft-content view that renders unpublished changes on the live site template, letting editors and reviewers see changes before they go live.
“Don’t approve copy changes from the CMS form alone — check them in preview mode first, since the rendered layout sometimes wraps text differently.”
Delivery and Integration
Story API / Content Delivery API — the endpoint Storyblok exposes to fetch published (or draft) story content as JSON for the frontend to render.
“The frontend never touches the Storyblok dashboard — it just calls the Content Delivery API and renders whatever bloks come back.”
Webhook — an HTTP callback Storyblok triggers on events like publishing a story, commonly used to trigger a static site rebuild.
“We wired a webhook so publishing any story in Storyblok kicks off a rebuild automatically — editors don’t need to ping us to deploy.”
Space — a Storyblok project/workspace containing its own stories, components, and access settings, roughly analogous to a “project” in other CMS tools.
“Staging and production are separate spaces, not just separate branches — content changes in one don’t automatically appear in the other.”
Common Mistakes
| Mistake | Correction |
|---|---|
| Calling a blok a “component” in editor-facing docs | Use “blok” with non-developers too — it’s the term editors will see in the UI itself. |
| Saying “the page is broken” for a missing field | Be specific — is a required field empty, or is a blok schema out of sync with the frontend’s expected props? |
| Assuming preview mode shows the same as production | Preview renders draft content on the live template, but caching or CDN behavior can still differ from production. |
| Treating “story” and “page” as interchangeable | A story can be a page, but it can also be a reusable content block referenced by other stories. |
Practice Exercise
- Explain, in two sentences, the difference between a blok and a story to a content editor who has never used Storyblok.
- Write a short webhook-setup PR description explaining that publishing a story now triggers a static site rebuild.
- Draft a message to an editor explaining why a layout change needs to be checked in preview mode before requesting approval.