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.
Related Resources
- English for Contentful Developers
- English for Headless CMS Developers
- English for Sanity CMS Developers
Navigating Nuances: Addressing Common Communication Challenges
For non-native English speakers working with Storyblok, mastering professional vocabulary isn’t just about knowing the technical terms – blocks, content types, story trees – it’s about understanding how those concepts are discussed in a collaborative development environment. A lot of miscommunication stems from subtle differences in phrasing and expectations around feedback. Consider this: receiving a comment like “This block needs more context” can be interpreted as simply lacking information, but actually implies the developer should clarify why that context is needed – perhaps it’s unclear how the block relates to the overall story or if its purpose isn’t fully defined. Similarly, stating “The styling is off” doesn’t give guidance; a better approach would be “Can you adjust the padding on this element to align with the brand guidelines?” These seemingly small shifts in wording have a huge impact on clarity and efficiency.
Another frequent challenge lies in describing changes during code reviews or PR descriptions. Developers often default to overly technical language, which can confuse non-technical stakeholders. Instead of saying “I’ve modified the JSON structure for the ‘hero’ block,” it’s more effective to explain: “I’ve updated the hero block’s data structure to improve performance and ensure consistent styling across all devices.” The key is translating technical details into understandable benefits – improved speed, better visual consistency, simplified maintenance. Furthermore, proactively stating your intentions (“I’m implementing this change to address the accessibility audit findings”) demonstrates awareness and builds trust within the team. Remember, clear communication minimizes ambiguity and facilitates smoother collaboration.
Finally, don’t be afraid to ask for clarification. It’s far better to admit you don’t understand something than to proceed based on assumptions. Phrases like “Could you elaborate on what you mean by ‘responsive’ in this context?” or “Can we discuss the rationale behind this decision?” demonstrate a willingness to learn and ensure everyone is on the same page. This proactive approach fosters a supportive environment where questions are valued, not perceived as weaknesses. Building confidence in your English communication skills will significantly improve your ability to contribute effectively within a Storyblok development team.
# Example CLI command for Storyblok (using their command-line tool) - demonstrating a simple block update
storyblok init --block-id 123456789 --title "Updated Hero Block" --content '{"text": "New hero text!"}'