Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
docs: explain the complete Content Engine workflow (#6403)
Oleg Isonenea17eaa3c4dc
diff --git a/docs/university/core-components/content-block.md b/docs/university/core-components/content-block.mdindex 0128f3773d..3a1a19dae5 100644--- a/docs/university/core-components/content-block.md+++ b/docs/university/core-components/content-block.md@@ -78,6 +78,10 @@ To insert a custom component such as Accordion into **MDX content**, first add iMoving, pasting, or duplicating content into an MDX region also checks the destination's Templates. Unsupported components are rejected before the tree changes, including components nested inside a pasted container.+Shared Slots cannot be used inside Content Block Templates. Duplicate the Slot+content into a regular template instead so each inserted MDX instance owns an+editable copy.+#### Prepare the Content Block1. Add the Content Block and design its shell in Design mode.@@ -331,6 +335,7 @@ Beyond adding new content, you can edit the existing content inside the Content## Related+- [Content Engine](../foundations/content-engine.md) – Build file-based sites with visually editable MDX articles- [Slot](slot.md) – Reusable component slots- [Modes](../foundations/modes.md) – Builder modes including Content mode- [Collection](collection.md) – Iterate over dynamic datadiff --git a/docs/university/foundations/assets.md b/docs/university/foundations/assets.mdindex 155ae9ecbf..7d99aa8f22 100644--- a/docs/university/foundations/assets.md+++ b/docs/university/foundations/assets.md@@ -111,6 +111,20 @@ already used in the selected parent folder are not saved.Duplicating a folder copies its nested folders and assets. Deleting a folderdeletes everything inside it, so review the confirmation before continuing.+### Use a folder as a content collection++Turn on **Use as content collection** when creating a folder, or choose it from+an existing folder's menu, when editors should create structured MDX entries+without writing frontmatter by hand. Webstudio adds `collection.json`, which+defines the entry fields, and an MDX entry template. The folder remains a+regular Assets folder.++Use **Configure collection** to define the form fields, starting content, and+the dynamic entry page. Editors can then choose **New entry**, update fields in+**Entry settings**, edit the source through **Edit file**, or choose **Open on+canvas** to edit the complete article visually. See [Content Engine](content-engine.md#make-the-folder-a-content-collection)+for collection setup, validation, and publishing behavior.+### Select and update multiple itemsSelect multiple assets and folders to move, copy, cut, duplicate, or deletediff --git a/docs/university/foundations/content-engine.md b/docs/university/foundations/content-engine.mdindex 3df3ff954d..de423a4d97 100644--- a/docs/university/foundations/content-engine.md+++ b/docs/university/foundations/content-engine.md@@ -10,12 +10,32 @@ truth, including their filenames, folders, metadata, and relative links. Youcan move the same files between projects or use them outside Webstudio withoutexporting them from a database first.+MDX is a widely used file format that combines Markdown with JSX. In Webstudio,+it lets designers pre-style every article element while editors write directly+on the canvas with a Notion-style interface. Editors can also work in the MDX+source, and AI agents can work through Webstudio MCP.++It brings Content mode to file-based sites without requiring an external CMS+or a runtime content database on the published site. Use it to:++- Query file fields and render hundreds of pages from one visual design.+- Edit complete MDX articles on the canvas with changes saved back to the file.+- Give editors pre-styled Markdown elements and custom interactive components.+- Create and edit structured entries through forms generated from a collection schema.+- Build or change the same setup with Webstudio MCP while keeping every setting+ available in the visual interface.+This guide creates a blog overview at `/blog` and one dynamic article page at`/blog/:slug`.To see the finished setup first, start with the[Markdown Blog marketplace template](https://webstudio.is/marketplace/templates/markdown-blog).+Watch the complete workflow, from the first MDX file to visual editing and+structured collection entries:++{% embed url="https://youtu.be/Sn-fhVajpgU" %}+<figure><img src="../../.gitbook/assets/content-engine-assets-structure.png" alt="Assets panel showing Markdown articles and their assets folder"><figcaption><p>Markdown articles stored alongside their assets</p></figcaption></figure>## Decide if the Content Engine fits@@ -25,7 +45,7 @@ the site and remain portable as Markdown, MDX, or JSON.Good fits include:-- Small blogs with text and images.+- Blogs with hundreds of text-and-image articles, within the limits below.- Portfolios, team directories, resource libraries, and case studies.- Small product catalogues with infrequently changed display data. Keep orders,inventory, and payments in an ecommerce system.@@ -51,17 +71,18 @@ using it for a content-heavy project.## Build it with MCPAn AI agent can complete this entire workflow through-[Webstudio MCP](../mcp.md). It can create the folders and Markdown files, upload-images, build both pages, configure the Assets resources, add the Collection,-bind the article directly, set the page metadata, and check the rendered result-with vision. Everything remains editable in the visual editor.+[Webstudio MCP](../mcp.md). It can create the folders and MDX files, upload+images, build both pages, configure the Assets resources, connect a Content+Block, add the content collection, set the page metadata, and check the rendered+result with vision. Everything remains editable in the visual editor.Give the agent an editable project share link when it asks for one, then make arequest such as:-> Use Webstudio CLI to build a blog with the Content Engine. Store the articles-> as Markdown files, create `/blog` and `/blog/:slug`, exclude drafts, and check-> both pages on desktop and mobile.+> Install Webstudio CLI and use MCP to build a blog with the Content Engine.+> Store complete articles in MDX files, create `/blog` and `/blog/:slug`, make+> every article field editable in Content mode, let editors create entries with+> a collection form, exclude drafts, and check both pages on desktop and mobile.The remaining steps explain the same workflow when you want to build or inspectit manually.@@ -85,6 +106,10 @@ in this guide use that ID to query only files in this folder.### Make the folder a content collection+This step is optional. The Assets queries and dynamic page work without a+collection. Add one when editors should create and update entries through forms+instead of editing MDX frontmatter by hand.+Turn on **Use as content collection** when you create the `posts` folder ifeditors should be able to add articles without writing MDX frontmatter. For anexisting folder, choose **Use as content collection** from its context menu,@@ -155,7 +180,8 @@ entries. The page must have one URL parameter, such as `/blog/:slug`.Webstudio fills the page parameter with the entry filename when you choose**Open on canvas** from an entry's menu or **Entry settings**. The action staysvisible but disabled until the collection has a compatible entry page; its help-points back to this setting. Creating an entry does not navigate automatically.+points back to this setting. If the page does not exist yet, finish step 5 and+then return to this setting. Creating an entry does not navigate automatically.The collection format uses a supported subset of JSON Schema draft 2020-12.The configurator exposes string, number, integer, boolean, and slug fields,@@ -228,11 +254,8 @@ number controls bound to these fields also show their collection errors. Fixingthe values clears the errors. A field error does not hide the entry, stop thecollection rendering, or block publication of unrelated changes.-These checks read bounded file prefixes for direct entries in the open folder,-with at most four reads at once. Frontmatter is cached by file revision while-that folder remains open. Changing the schema rechecks cached values without-downloading unchanged entries again. A failed read is reported separately from-field errors and can be retried with **Check again**.+A failed read is reported separately from field errors and can be retried with+**Check again**.The configurator rejects Integer limits that leave no possible whole number.Slug limits must allow at least one character, even when minimum length is unset.@@ -241,14 +264,6 @@ saving collection settings. These match automatically generated filenames.Custom filename patterns require a Slug field. Existing configurations remainreadable so their content can still be repaired and published.-Builder shares collection configuration loading across Assets, file editors, and-bound property controls. It groups the already-synchronized asset metadata once-per update and downloads the active collection's configuration and template once-for all consumers. Editing an entry does not download those unchanged files again.-Changing the configuration or template, retrying a failed read, or changing project-or access token refreshes this state. Entry validation still reads frontmatter as-described above; sharing configuration does not remove those reads.-A collection folder accepts entries, supporting assets, and subfolders. Use**New entry** for filenames selected by the entry patterns. Files excluded bythe patterns behave like ordinary assets: upload, create, paste, move, rename,@@ -275,11 +290,11 @@ appear in Assets query results.## 2. Create an articleIf `posts` is a content collection, choose **New entry** and fill in its form.-Otherwise, create the file and frontmatter manually:+Otherwise, create the MDX file and frontmatter manually:1. Open `blog/posts` in the Assets panel.2. Open the add menu and choose **Create text file**.-3. Name the file `hello-world.md`.+3. Name the file `hello-world.mdx`.4. Add the article metadata between the two `---` lines, followed by thearticle body:@@ -401,8 +416,7 @@ page-level **Dynamic data**:5. Under **Content**, choose **Metadata only**. The overview does not rendercomplete article bodies.6. Add these filters:- - `extension` **equals** `"mdx"` for collection entries, or `"md"` for the- manually created Markdown files in this guide+ - `extension` **equals** `"mdx"`- `folder id` **equals** the quoted `posts` folder ID- `properties.draft` **does not equal** `true`7. Sort `properties.publishedAt` in descending order. Add `id` in ascending@@ -448,10 +462,10 @@ Add another Assets resource to the page-level **Dynamic data**:`properties.featureImage.src`, `properties.featureImage.description`, and`properties.author`.4. Under **Result**, choose **Exactly one**.-5. Under **Content**, choose **Markdown body reference**.+5. Under **Content**, choose **Metadata only**. The Content Block loads the+ matching MDX file directly.6. Add these filters:- - `extension` **equals** `"mdx"` for collection entries, or `"md"` for the- manually created Markdown files in this guide+ - `extension` **equals** `"mdx"`- `folder id` **equals** the quoted `posts` folder ID- `properties.slug` **equals** `system.params.slug`- `properties.draft` **does not equal** `true`@@ -462,24 +476,42 @@ Add another Assets resource to the page-level **Dynamic data**:reports an error if two articles use the same slug. You do not need aCollection on the article page.-**Markdown body reference** keeps article bodies out of the published content-database. Webstudio first finds the matching article, then loads only that-Markdown body from Assets.--## 6. Bind the article+**Metadata only** keeps article bodies out of the published content database.+The resource finds the matching article and returns its Asset ID. The Content+Block then loads that MDX file directly.-Bind the article components directly to `post.data`:+If `posts` is a content collection, return to **Collection settings → Entry+page** and select this dynamic page. This enables **Open on canvas** for its+entries.-- Heading: `post.data.properties.title`-- Author: `post.data.properties.author`-- Image source: `post.data.properties.featureImage.src`-- Image alternative text:- `post.data.properties.featureImage.description ?? post.data.properties.title`-- Markdown Embed code: `post.data.content.text`+## 6. Bind the article-Add a [Markdown Embed](../core-components/markdown-embed.md) for the body. Style-its nested headings, paragraphs, links, lists, and images once; the styles apply-to every article.+Add a [Content Block](../core-components/content-block.md#store-content-in-an-mdx-file)+and bind its **Source** to `post.data.id`. Every Assets query result includes its+Asset ID, even when file metadata is disabled. The Content Block loads the+matching article and adds an **MDX content** region for its body.++Build the complete article inside the Content Block:++- Bind the heading directly to `document.frontmatter.title`.+- Bind the author directly to `document.frontmatter.author`.+- Bind the Image source directly to+ `document.frontmatter.featureImage.src` and make the binding writable.+- Bind the Image alternative text to+ `document.frontmatter.featureImage.description`.+- Place the **MDX content** region where the article body should render.+- Style the standard Markdown elements in **Templates**, then add any custom+ interactive elements editors should be able to insert.++Keep each editable value directly bound to one frontmatter field. Computed+expressions remain read-only. Put fixed wording in separate text elements and+use a Date Time component for dates so Content mode shows the appropriate+controls.++Editors can now change the title, author, images, dates, body, links, and custom+interactive elements directly on the canvas. These changes save back to the MDX+file. Verify every article-owned value in Content mode before handing the site+to an editor.In Page Settings, bind the fields needed for search and sharing:@@ -490,29 +522,13 @@ In Page Settings, bind the fields needed for search and sharing:The status expression returns a real 404 when no article matches the URL.-### Edit the complete article in Content mode--The setup above uses a `.md` file and Markdown Embed when the article body is-edited in the file editor. Use an `.mdx` file connected to a-[Content Block](../core-components/content-block.md#store-content-in-an-mdx-file)-when an editor should change the article visually in Content mode.--1. Name the article files with the `.mdx` extension and change the resource's- `extension` filter from `md` to `mdx`.-2. Change the article resource's **Content** setting to **Metadata only**. The- Content Block loads the selected file directly, so the resource does not- need to return its body.-3. Replace the Markdown Embed with a Content Block and place its **Body** outlet- where the article body should render.-4. Bind the Content Block's **Source** to `post.data.id`. Every Assets query- result includes its Asset ID, even when file metadata is disabled.-5. Move the article title, image, excerpt, and other designed fields inside the- Content Block shell. Bind them directly to values such as- `document.frontmatter.title` and `document.frontmatter.featureImage.src`.--Editors can now change the MDX body and directly bound frontmatter values on-the canvas. Computed frontmatter expressions and values reached through a-document `$ref` remain read-only; edit their source file instead.+### Render a read-only Markdown body++Use a `.md` file and [Markdown Embed](../core-components/markdown-embed.md) only+when the article body does not need visual editing. Set the article resource's+`extension` filter to `md` and **Content** to **Markdown body reference**, then+bind the Markdown Embed code to `post.data.content.text`. Style its nested+document elements once for every article.## 7. Publish the article@@ -530,7 +546,7 @@ filter. The metadata field does not automatically remove an article from acustom sitemap.To publish another collection article, choose **New entry**. For the manual-workflow, duplicate the Markdown file and change its title, slug, publication+workflow, duplicate the MDX file and change its title, slug, publicationdate, image, and body. The existing overview and dynamic page will render itwithout another page design.@@ -639,6 +655,7 @@ reference cycles fail instead of returning partial data.- [Content Engine reference](content-engine-reference.md) – Check query fields, modes, diagnostics, references, and limits- [Assets](assets.md) – Create, edit, organize, and reference project files+- [Content Block](../core-components/content-block.md) – Design and visually edit MDX articles- [Data variables](variables.md) – Define resources and understand their scope- [Collection](../core-components/collection.md) – Render article lists- [Markdown Embed](../core-components/markdown-embed.md) – Render and style an article bodydiff --git a/docs/university/foundations/modes.md b/docs/university/foundations/modes.mdindex aa6828ce8a..76610905cd 100644--- a/docs/university/foundations/modes.md+++ b/docs/university/foundations/modes.md@@ -38,6 +38,8 @@ In Content mode, the following actions can be performed:- Add and edit links within text inside Content Blocks- Upload and change images inside Content Blocks when their props are available in Content mode- Insert instances of templates to designer-specified regions called [Content Blocks](../core-components/content-block.md)+- Edit MDX article fields and bodies inside connected Content Blocks, with changes saved back to the source file+- Create and edit entries in [content collection folders](content-engine.md#make-the-folder-a-content-collection)- Create pages from existing [Page templates](page-templates.md), if the designer provided them- Edit safe page settings: page name, static path, title, description, search visibility, language, social image, and custom metadata- Publish the site (optional [permission](share-links.md#types-of-share-links))@@ -56,6 +58,7 @@ Here’s what you need to know:- Users on the Pro tier can create a [Share link](share-links.md) with “Content” permission- Editors can perform [these actions](modes.md#allowed-actions)- You can create templates that editors can insert with [Content Blocks](../core-components/content-block.md)+- You can connect MDX files to Content Blocks and configure collection folders so editors can create and edit complete articles visually- You can create [Page templates](page-templates.md) that editors can use to create new pages- Editors can update safe page metadata, but dynamic routes, redirects, authentication, document type, and status-code logic remain under designer control@@ -94,6 +97,8 @@ Here’s what you need to know:<figure><img src="../../.gitbook/assets/add-content.png" alt="Adding a template"><figcaption></figcaption></figure>+- In a [content collection](content-engine.md#make-the-folder-a-content-collection), choose **New entry** to create an article with the form provided by the designer. Use **Entry settings** to edit its fields, **Edit file** to edit its source, or **Open on canvas** to edit the complete article on its configured dynamic page.+- If the designer provided [Page templates](page-templates.md), you can create new pages from them and edit page details like name, path, SEO title, description, language, social image, and custom metadata.- Changes save in real time, but you must publish them before they go live. Select **Publish** in the top bar, choose the destinations, and publish. **Publish** may be unavailable if the designer did not grant publishing permission.