docs: Document MDX-backed Content Blocks (#6273)

## Summary - Document how people create, connect, edit, validate, and publish MDX-backed Content Blocks. - Document the complete MCP workflow, including scoped expression sources, frontmatter updates, diagnostics, conflicts, and disconnect behavior. - Add two focused screenshots for the human workflow. - Fix issues found by a low-reasoning MCP agent while executing every documented workflow. Ref #6182 ## Implementation notes - Connection confirmation uses the public `confirmReplacement` field because `confirm` is reserved as a hidden transport field. - MCP edits frontmatter with `update-content-block-frontmatter`; materialized MDX elements are not persistent targets for generic instance mutation tools. - Reload now intentionally discards a conflicted local source and accepts the Asset's latest storage revision before an edit is reapplied. - Generated MCP documentation and runtime contracts are updated from their source files. ## Checklist - [x] Document the human MDX Content Block workflow. - [x] Document MCP discovery, connection, editing, diagnostics, frontmatter, dynamic sources, conflicts, and disconnection. - [x] Add only screenshots that clarify otherwise hard-to-describe UI steps. - [x] Test every documented MDX capability through the local MCP CLI with a low-reasoning agent. - [x] Reproduce and fix the replacement-confirmation schema mismatch. - [x] Reproduce and fix persistent-session conflict reload and reapply. - [x] Add regression tests that failed before each product fix and pass afterward. - [x] Regenerate runtime contracts and generated MCP documentation. - [x] Review authoritative `docs/` content and update affected pages. - [x] Run affected tests, typechecks, formatting, and diff checks. ## Verification - Project Build: 208 affected tests passed. - Content Engine Asset session: 8 tests passed. - CLI documentation tests: 14 tests passed. - MCP docs generator: 3 tests passed. - Content Engine, Project Build, CLI, and MCP docs typechecks passed. - `pnpm oxfmt --check` passed. - `git diff --check` passed. - Low-reasoning MCP evaluation passed all documented workflows, including a real two-client revision conflict, reload, reapply, and final saved inspection.
2026-10-23 03:27:27 +09:00 · 2026-08-31 18:39:05 +02:00
1 parent 8718feb465
commit 1b48716ff4
@@ -10,8 +10,7 @@

 - [Blog](https://webstudio.is/blog)
 - [Documentation](https://docs.webstudio.is/)
- [Brand and Product Design](https://docs.webstudio.is/contributing/contributing-for-designers)
- [Contributing Guide for Devs](https://docs.webstudio.is/contributing/contributing-for-developers)
+- [Contributing](https://docs.webstudio.is/contributing/contributions)
 - [Builder Issues Tracker](https://github.com/webstudio-is/webstudio/issues)
 - [Roadmap](https://github.com/orgs/webstudio-is/projects/11)

@@ -53,13 +53,19 @@ const isAssetContentResponse = (response: Response, method = "PUT") =>
  response.url().includes("/rest/assets/") &&
  response.url().includes("/content");

-const waitForAssetWrite = (page: Page, sourceIncludes?: string) =>
+const waitForAssetWrite = (
+  page: Page,
+  sourceMatches?: (source: string) => boolean
+) =>
  page.waitForResponse(
-    (response) =>
-      isAssetContentResponse(response) &&
-      response.status() === 200 &&
-      (sourceIncludes === undefined ||
-        response.request().postData()?.includes(sourceIncludes) === true),
+    (response) => {
+      const source = response.request().postData() ?? "";
+      return (
+        isAssetContentResponse(response) &&
+        response.status() === 200 &&
+        (sourceMatches === undefined || sourceMatches(source))
+      );
+    },
    { timeout: 30_000 }
  );

@@ -465,7 +471,9 @@ test("Empty MDX content supports insertion and keeps the next paragraph focused"
    .last()
    .waitFor({ state: "visible" });
  await page.keyboard.press("Escape");
-  const paragraphWrite = waitForAssetWrite(page, "Focused paragraph");
+  const paragraphWrite = waitForAssetWrite(page, (source) =>
+    source.includes("Focused paragraph")
+  );
  const paragraphMetadataWrite = waitForChangeToBeSaved({ page });
  await page.keyboard.type("Focused paragraph");
  const paragraphId = await paragraphEditor.getAttribute("data-ws-id");
@@ -484,6 +492,13 @@ test("Empty MDX content supports insertion and keeps the next paragraph focused"
  if (emptyParagraphId === null) {
    throw new Error("Expected the new paragraph instance id");
  }
+  const finalWrite = waitForAssetWrite(
+    page,
+    (source) =>
+      source.includes("# First heading") &&
+      source.includes("Focused paragraph") &&
+      source.includes('ws:tag="p"') === false
+  );
  await page.keyboard.press("ControlOrMeta+A");
  await page.keyboard.press("Backspace");
  await page.keyboard.press("Backspace");
@@ -499,7 +514,6 @@ test("Empty MDX content supports insertion and keeps the next paragraph focused"
  ) {
    throw new Error("Expected the previous paragraph to regain focus");
  }
-  const finalWrite = waitForAssetWrite(page);
  await page.mouse.click(5, 5);
  const finalSource = (await finalWrite).request().postData() ?? "";
  if (
@@ -58,14 +58,10 @@ Our getting started guide will help you navigate through building your first Web
 [FAQ.md](basics/FAQ.md)
 {% endcontent-ref %}

-### Looking to contribute to Webstudio?
+## Looking to contribute to Webstudio?

-{% content-ref url="contributing/contributing-for-designers.md" %}
-[contributing-for-designers.md](contributing/contributing-for-designers.md)
-{% endcontent-ref %}
-
-{% content-ref url="contributing/contributing-for-developers.md" %}
-[contributing-for-developers.md](contributing/contributing-for-developers.md)
+{% content-ref url="contributing/contributions.md" %}
+[contributions.md](contributing/contributions.md)
 {% endcontent-ref %}

 {% content-ref url="contributing/marketplace.md" %}
@@ -149,8 +149,7 @@

 ## Contributing

-* [🧑‍🎨 Contributing for Designers](contributing/contributing-for-designers.md)
-* [🧑‍💻 Contributing for Developers](contributing/contributing-for-developers.md)
+* [Contributions](contributing/contributions.md)
 * [Contributing to the Marketplace](contributing/marketplace.md)

 ***
@@ -86,11 +86,11 @@ Webstudio automatically converts images to WebP and resizes them to fit webpage

 <details>

-<summary>🚀 How can I use Webstudio today, and how will it evolve?</summary>
+<summary>🚀 What can I build with Webstudio today?</summary>

-Currently, Webstudio excels in building super fast, responsive, dynamic websites. Future enhancements include linked CSS editors, animations engine, and real-time collaboration. Its open-source nature and API integration capabilities allow for extensive customization and connectivity with various services.
+Webstudio builds responsive static and dynamic websites with visual CSS controls, animations, data Resources, Content mode, the Content Engine, and accessible components. You can work in the visual Builder or let an AI agent edit the same project through Webstudio MCP. Projects can be published to Webstudio Cloud or exported for self-hosting.

-[Webstudio Vision Document](https://webstudiois.notion.site/Vision-f52ed097ccaa410eb05076981d446c2f)
+[Webstudio features](https://webstudio.is/features), [Webstudio roadmap](https://wstd.us/roadmap)

 </details>

@@ -6,32 +6,32 @@ Webstudio 101 Playlist

 This video series is a quick overview of the most important parts of the builder to get you up to speed.

-### 🚀 Signup to Webstudio
+## 🚀 Sign up for Webstudio

 1. Visit [Webstudio](https://webstudio.is/) and click on the "start building" or "sign in" button.
 2. Create an account using either Google or Github.

-### 🌟 Create a New Project or Import a Template
+## 🌟 Create a new Project or import a template

 Once logged in, you'll be taken to your dashboard. Here, you can view your existing projects and have the option to create a new blank project or start with a premade template.

-### 🖥 Understand the Builder Interface
+## 🖥 Understand the Builder interface

 Understanding the interface is key to effectively using any new tool. Familiarize yourself with Webstudio's builder – the heart of your website creation. The Components panel houses elements like text, images, links, and more, which you can drag onto your canvas. For an in-depth guide, read our [Intro to the Anatomy of the Webstudio builder](../university/foundations/anatomy-of-the-webstudio-builder.md).

-### 🎨 Use Design tokens
+## 🎨 Use design tokens

 Webstudio utilizes Design tokens for styling, offering consistency across platforms. These reusable styles help avoid naming conflicts and dependency issues common in large projects. Learn more about [Design tokens in Webstudio](../university/foundations/design-tokens.md).

-### 🔧 Experiment With Components
+## 🔧 Experiment with components

 Components are the building blocks of your website. Experiment with basic ones like Text and Image, or delve into advanced components like HTML Embeds or Radix. Customize each component’s properties under "Settings."

-### 🌐 Preview & Publish
+## 🌐 Preview and publish

 Once you're satisfied with your creation, use the 'Preview' button at the top right corner before publishing it live on the internet! For more details, check our [Publishing and custom domains Guide](../university/foundations/publishing-and-custom-domains.md).

-### 💬 Join the Community
+## 💬 Join the community

 Learning a new tool takes time, so don't be discouraged by initial challenges. Keep exploring, experimenting, and [join the Webstudio community](https://wstd.us/community) for support and inspiration.

@@ -4,9 +4,9 @@ description: Community-made courses

 # 🤓 Courses

-### [Webstudio Essentials: 0 to Complete Website With SEO](https://shop.createtoday.io/l/webstudio-essentials)
+## [Webstudio Essentials: 0 to Complete Website With SEO](https://shop.createtoday.io/l/webstudio-essentials)

-<figure><img src="../.gitbook/assets/webstudio-essentials-course.png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../.gitbook/assets/webstudio-essentials-course.png" alt="Webstudio Essentials course page"><figcaption></figcaption></figure>

 ## Related

@@ -4,13 +4,13 @@

 Webstudio is an open-source visual development platform that empowers designers and developers to create responsive web designs with ease. Bridging the gap between design and code, it allows users to visually build while maintaining control over the underlying HTML, CSS, and JavaScript.

-### 🧑‍🎨 For Designers
+## 🧑‍🎨 For Designers

 Webstudio offers a powerful platform for designers to bring their creative visions to life, without needing extensive coding knowledge. Its intuitive visual interface enables the construction of layouts, styling of components, and animation of elements in real-time on a live canvas. This direct manipulation of design elements facilitates immediate feedback and accelerates iteration cycles.

-### 🧑‍💻 For Developers
+## 🧑‍💻 For Developers

-Developers will appreciate Webstudio's flexibility and extensibility. It simplifies web development with its visual interface, yet provides full access to the underlying code. Developers can create custom components with complex logic or specific integrations, harnessing the power of coding while benefiting from Webstudio's streamlined visual workflows. As an open-source tool, Webstudio offers the freedom to extend functionality as needed and contribute to the enhancement of its features.
+Developers can combine the visual editor with Resources, expressions, HTML Embed, and Webstudio MCP. Projects can be exported, self-hosted, or extended by contributing to the open-source Builder. Webstudio does not currently provide a visual workflow for defining new reusable component types; use Slots for reusable project content and HTML Embed for custom code.

 ## Related

@@ -32,5 +32,4 @@ Here you will find real-time updates and can see exactly what our team is workin
 - [Webstudio Blog](https://webstudio.is/blog) – Read the latest news and tutorials
 - [Intro](intro.md) – Learn what Webstudio is and who it's for
 - [FAQs](FAQ.md) – Common questions and answers about Webstudio
- [Contributing for Designers](../contributing/contributing-for-designers.md) – Ways designers can contribute to Webstudio
- [Contributing for Developers](../contributing/contributing-for-developers.md) – How to contribute code to Webstudio
+- [Contributions](../contributing/contributions.md) – Contribute to Webstudio as a designer or developer
@@ -1,26 +0,0 @@
-# 🧑🎨 Contributing for Designers
-
-Webstudio is not just a tool, but also a community. As an open-source platform, it thrives on the contributions of its users. If you're a designer wondering how you can contribute to the growth and development of Webstudio, here are some ways:
-
-1.  #### Share Your Designs
-
-    One of the most straightforward ways designers can contribute is by sharing their designs built with Webstudio in [our community](https://wstd.us/community). This could be in the form of templates or individual components that others can use as starting points for their projects. We would also love to share your design showcases with the rest of the Webstudio audience via our socials.
-2.  #### Create Tutorials & Guides
-
-    If you've mastered certain aspects of using Webstudio, consider creating tutorials or guides to help other users navigate those features more effectively. Tag us in what you create and we'll help spread the word.
-3.  #### Participate in Community Discussions
-
-    Join discussions on forums or social media platforms where ideas about new features or improvements are being discussed - your perspective as a designer will add unique value. If you're looking for a place to start you can join the [Official Webstudio Community](https://wstd.us/community).
-4.  #### Contributing to the Webstudio Builder UI
-
-    If you want to contribute to the Builder UI, your first step is to become familiar with our design system in Figma. Start with the first page of our [Design Docs](https://www.figma.com/community/file/1314046494721696168). And for our design system & components see the [Webstudio Library](https://www.figma.com/community/file/1314044856015300004). Please read the docs carefully and thoroughly so you can use our design system properly to create a UI that looks like it's a natural part of Webstudio. If any part of the design is confusing or intimidating you can reach out via our [Discord](https://discord.gg/UNdyrDkq5r) with questions or feedback. We're also happy to give a tour of the design system to anyone who asks.
-5.  #### Contributing to the Webstudio Brand
-
-    If you want to contribute to our brand design or use our brand assets, you can refer to our [Brand Guidelines](https://www.figma.com/community/file/1253220655531199360).
-
-## Related
-
- [Contributing for Developers](contributing-for-developers.md) – Technical contribution guide
- [Contributing to the Marketplace](marketplace.md) – Submit templates and sections
- [Marketplace](../university/marketplace.md) – Browse community-contributed templates
- [Craft](../university/craft.md) – The standard for building with Webstudio
@@ -1,18 +1,29 @@
-# 🧑‍💻 Contributing for Developers
+# Contributions
+
+Contribute fixes and improvements to Webstudio as a designer or developer.

 ## Process

 If you want to contribute and don't know where to start, here is a step-by-step for a complete lifecycle, from idea to deployment.

 1. If you have an idea that is not already in [issues](https://github.com/webstudio-is/webstudio/issues), open an issue or reach out on [Discord](https://wstd.us/community).
-2. If you are a DEVELOPER, and you want to contribute to the Builder UI, your first step is to become familiar with our design system in figma. Start with the first page of our [Design Docs](https://www.figma.com/file/xCBegXEWxROLqA1Y31z2Xo/%F0%9F%93%96-Webstudio-Design-Docs?type=design&node-id=234%3A36754&t=w3VxT162RQF0gTrI-1). And for our design system & components see the [Webstudio Library](https://www.figma.com/file/sfCE7iLS0k25qCxiifQNLE/%F0%9F%93%9A-Webstudio-Library?type=design&node-id=2647%3A10046&t=f4xr8mcumXfXkHVh-1). Please read the docs carefully and thoroughly so you can use our design system properly to create a UI that looks like it's a natural part of Webstudio. If any part of the design is confusing or intimidating you can reach out to us on Discord with questions or feedback.
-3. After submitting an enhancement or a bug, we need to agree on a solution. You can jump into implementation right away, but be aware that we have to agree on the solution in the end. Communicating the problem you are solving and why you think the approach you are taking is the best is key for a quick process.
+2. After submitting an enhancement or a bug, we need to agree on a solution. You can jump into implementation right away, but be aware that we have to agree on the solution in the end. Communicating the problem you are solving and why you think the approach you are taking is the best is key for a quick process.

   In fact, we are happy to help you communicate your ideas, so if you are not sure - talk to us on discord.

-4. When the implementation is in a mergeable state, a core team member will deploy it to production.
+3. When the implementation is in a mergeable state, a core team member will deploy it to production.

-## Running the Webstudio Project Using VS Code
+## Contributions for designers
+
+Open the Webstudio repository in a local coding agent such as Codex and ask it to start the Builder locally. Open the URL it provides, then describe the changes you want and review them in the running interface.
+
+The agent can handle setup, make the code changes, run the relevant checks, and help prepare the contribution. Follow the process above so the problem and solution are agreed before the change is merged.
+
+## Contributions for developers
+
+Before contributing to the Builder UI, become familiar with the [Design Docs](https://www.figma.com/file/xCBegXEWxROLqA1Y31z2Xo/%F0%9F%93%96-Webstudio-Design-Docs?type=design&node-id=234%3A36754&t=w3VxT162RQF0gTrI-1) and [Webstudio Library](https://www.figma.com/file/sfCE7iLS0k25qCxiifQNLE/%F0%9F%93%9A-Webstudio-Library?type=design&node-id=2647%3A10046&t=f4xr8mcumXfXkHVh-1). Use the established design system so new UI feels like a natural part of Webstudio. Ask questions or share feedback on [Discord](https://wstd.us/community).
+
+## Running the Webstudio project using VS Code

 ### Prerequisites

@@ -99,7 +110,6 @@ You are done! 🎉

 ## Related

- [Contributing for Designers](contributing-for-designers.md) – Ways designers can contribute to Webstudio
 - [Contributing to the Marketplace](marketplace.md) – Submit templates and sections
 - [FAQs](../basics/FAQ.md) – Common questions including licensing information
 - [Roadmap & Links](../basics/roadmap-and-links.md) – See what the team is working on
@@ -43,5 +43,5 @@ Learn more about the [Marketplace](../university/marketplace.md).

 - [Marketplace](../university/marketplace.md) – Browse and use marketplace templates
 - [Craft](../university/craft.md) – The recommended standard for building templates
- [Contributing for Designers](contributing-for-designers.md) – Other ways designers can contribute
+- [Contributions](contributions.md) – Contribute to Webstudio as a designer or developer
 - [Design tokens](../university/foundations/design-tokens.md) – Create consistent, reusable styles
@@ -2,11 +2,11 @@

 As a thank you to our earliest adopters, we've decided to increase the limits of all existing accounts. Here below are the new limits to each account type:

-You can find your plan name from your dashboard beside your profile image as shown below.
+You can find your plan name in the Dashboard beside your profile image.

-<figure><img src="../.gitbook/assets/dashboard-plan-name.png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../.gitbook/assets/dashboard-plan-name.png" alt="Dashboard profile menu showing the current plan name"><figcaption></figcaption></figure>

-### Webstudio LTDs
+## Webstudio LTDs

 Purchase link: [https://wstd.us/pricing](https://wstd.us/pricing)

@@ -17,7 +17,7 @@ Purchase link: [https://wstd.us/pricing](https://wstd.us/pricing)
 | LTD T2    | unlimited    | 2M             |
 | LTD T3    | unlimited    | unlimited      |

-### RocketHub LTDs
+## RocketHub LTDs

 No longer available for purchase.

@@ -27,7 +27,7 @@ No longer available for purchase.
 | RocketHub T2 | unlimited    | 1M             |
 | RocketHub T3 | unlimited    | 2M             |

-### Appsumo LTDs
+## AppSumo LTDs

 No longer available for purchase.

@@ -9,7 +9,9 @@ description: This page highlights where to get support for all Webstudio custome
 If you're looking to upgrade your account and wish to receive a credit for any previous purchase, follow the below steps:&#x20;

 - Visit [https://webstudio.is/pricing](https://webstudio.is/pricing)
- Select the "Existing Lifetime Customer, Click here" text as illustrated below. ![](../.gitbook/assets/upgrade-account-pricing.png)
+- Select **Existing Lifetime Customer, Click here**.
+
+  ![Pricing page with the Existing Lifetime Customer link](../.gitbook/assets/upgrade-account-pricing.png)
 - Fill out the upgrade request form.&#x20;

 ## RocketHub account issues
@@ -18,7 +20,7 @@ If you're having trouble with an activation through a RocketHub purchase, please

 ## AppSumo account issues

-If you're having trouble activating your AppSumo license please read [this article](../errors/appsumo-redemption-failed.md).&#x20;
+If you're having trouble activating an AppSumo license, ask for help in the [Webstudio community](https://wstd.us/community). Do not post license codes, authentication links, or other private account information.

 ## Any other type of support

@@ -27,6 +29,5 @@ All other support is run directly via our community. We have a thriving communit
 ## Related

 - [Account Limits](account-limits.md) – View domain and pageview limits for different plans
- [AppSumo Redemption Failed](../errors/appsumo-redemption-failed.md) – Troubleshoot AppSumo activation issues
 - [FAQs](../basics/FAQ.md) – Common questions and answers about Webstudio
 - [Roadmap & Links](../basics/roadmap-and-links.md) – Official links and community resources&#x20;
@@ -192,7 +192,7 @@ Build a static site with:
 npx webstudio build --template ssg
 ```

-Please review [the limitations](self-hosting/#ssg-limitations) of using the static site export instead of dynamic templates.
+Please review [the limitations](self-hosting/#static-site-limitations) of using the static site export instead of dynamic templates.

 ## Other workflows

@@ -12,7 +12,7 @@ The Blockquote Component is used to highlight quoted content on a webpage, enhan

 ---

-### How to use the Blockquote Component
+## How to use the Blockquote component

 The "Blockquote" component can be found in Components > Text, and you can place it on your canvas by dragging and dropping it or clicking it in the Components panel. To edit the content of your Blockquote instance, simply double-click it.

@@ -20,7 +20,7 @@ Once the component is placed on your canvas, you can customize its appearance us

 For more on Design tokens in Webstudio, refer to [this guide](../foundations/design-tokens.md).

-### Styling a Blockquote
+## Styling a Blockquote

 By default, Blockquote components include padding on the left and right, along with a left border. You can customize these in the Style panel:

@@ -31,15 +31,16 @@ When using a Cite tag inside your blockquote, you may want to change its display

 ---

-### How to attribute a Blockquote
+## How to attribute a Blockquote

 It is a good practice to attribute the quoted text you use in a blockquote with the source's title, author, publication, URL, or any relevant information that identifies where the quote came from. This maintains transparency and credibility in your content. It also allows readers to verify the accuracy of the information and fosters ethical use of others' words.

 You can add an attribution or citation by using the “Cite” property in your Blockquote instance settings or with the “Cite” Tag from a Text component.

-#### Using the "Cite" Property
+### Using the Cite property
+
+<figure><img src="../../.gitbook/assets/blockquote-cite-property.avif" alt="Blockquote Cite property in the Settings panel"><figcaption></figcaption></figure>

-<figure><img src="../../.gitbook/assets/blockquote-cite-property.avif" alt=""><figcaption></figcaption></figure>

 If you want to include a URL link as a citation:

@@ -49,9 +50,10 @@ If you want to include a URL link as a citation:

 Please note that this value will not be visible to the end-user.

-#### Using the “Cite” Tag
+### Using the Cite tag
+
+<figure><img src="../../.gitbook/assets/blockquote-cite-tag.avif" alt="Cite tag selected for text inside a Blockquote"><figcaption></figcaption></figure>

-<figure><img src="../../.gitbook/assets/blockquote-cite-tag.avif" alt=""><figcaption></figcaption></figure>

 If you want to include a Name/Title as a citation alongside your Blockquote:

@@ -72,7 +72,7 @@ It's unclear why each item is correct or incorrect by just looking at the image,

 Add the Collection component to the canvas and either manually enter data (less common) or [bind data](../foundations/expression-editor.md#binding) to it (more common).

-**The Collection iterates over the array, so you must bind just the array portion of your variable to it. See** [**What's an Array**](collection.md#whats-an-array) **for more info.**
+**The Collection iterates over the array, so you must bind just the array portion of your variable to it. See** [**What's an array or object?**](collection.md#whats-an-array-or-object) **for more info.**

 Optionally, rename the default Collection Item variable to something more semantic. If you are iterating over blog posts, name it "Blog Post."

@@ -88,7 +88,7 @@ When working with [Radix Components](../radix/), you might want to dynamically g

 ### Accordions

-<figure><img src="../../.gitbook/assets/accordion-collection.png" alt=""><figcaption><p>The Item has a unique value from the dynamic data bound to the Value field</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/accordion-collection.png" alt="Accordion Item settings with a unique collection value bound to the Value property"><figcaption><p>The Item has a unique value from the dynamic data bound to the Value field</p></figcaption></figure>

 ### Tabs

@@ -98,9 +98,9 @@ Tab Triggers and Tab Contents maintain their relationship by having the same val

 <div>

-<figure><img src="../../.gitbook/assets/tab-trigger.png" alt=""><figcaption><p>Tab Trigger with custom value</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/tab-trigger.png" alt="Tab Trigger settings with a custom Value property"><figcaption><p>Tab Trigger with custom value</p></figcaption></figure>

-<figure><img src="../../.gitbook/assets/tab-content.png" alt=""><figcaption><p>Tab Content with custom value</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/tab-content.png" alt="Tab Content settings with the corresponding custom Value property"><figcaption><p>Tab Content with custom value</p></figcaption></figure>

 </div>

@@ -15,8 +15,8 @@ Designers can create a library of templates, from little cards to fully built se

 Next is a breakdown of Content Block by mode:

-1. [Design mode](content-block.md#design-mode) ⬇️
-2. [Content mode](content-block.md#content-mode) ⬇️
+1. [Design mode](content-block.md#content-block-in-design-mode) ⬇️
+2. [Content mode](content-block.md#content-block-in-content-mode) ⬇️

 ## Content Block in Design mode

@@ -40,7 +40,7 @@ Notice that the child of Content Block is Templates.&#x20;

 Drag/build the various instances you want to provide editors here.

-For example, your client wants to update the section under the hero with the latest promotion. Sometimes the promotion is for an event while other times it’s a product. You can create those two designs, add them to “Templates” within Editable Block, and your client can insert instances of the desired template and edit its content.
+For example, your client wants to update the section under the hero with the latest promotion. Sometimes the promotion is for an event while other times it’s a product. You can create those two designs, add them to “Templates” within Content Block, and your client can insert instances of the desired template and edit its content.

 {% hint style="info" %}
 Editors don’t have access to the Style Panel, so be sure to provide fully designed templates.
@@ -50,13 +50,15 @@ Every top-level instance within Templates will appear in Content mode like this:

 <div><figure><img src="../../.gitbook/assets/templates-design-mode.png" alt="Templates in Design mode"><figcaption><p>Templates in Design mode</p></figcaption></figure> <figure><img src="../../.gitbook/assets/templates-content-mode.png" alt="Template in Content mode"><figcaption><p>Template in Content mode</p></figcaption></figure></div>

+
 Each time they insert a template, its copy appears inside the Content Block's Body outlet, alongside any initial body content. The Templates container remains protected source material.

 ### Step 3: Add an initial setup (optional)

 Optionally, you can add instances inside the Content Block's Body outlet.

-<figure><img src="../../.gitbook/assets/startingpoint-content-block.png" alt="" width="357"><figcaption><p>The "Feature" instances are provided as a starting point</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/startingpoint-content-block.png" alt="Initial Feature instances inside a Content Block Body outlet" width="357"><figcaption><p>The Feature instances are provided as a starting point</p></figcaption></figure>
+

 Doing so will provide an initial setup for editors.

@@ -64,19 +66,54 @@ Editors can delete children of the Body outlet. They cannot delete the designed

 ### Store content in an MDX file

-In Design mode, use the **Source** property under **Properties & attributes** to connect a `.mdx` file from Assets. Create the file in Assets first, then select it directly or bind the property to an Asset ID. The file becomes the source of the Body outlet's children; the designed shell and Templates container remain part of the project.
+Connect a `.mdx` file when the Content Block's body should live in Assets instead of the project's regular instance data. The designed shell and Templates list remain in the project. Markdown `.md` files cannot be connected to a Content Block.

-Connecting a file replaces the Body outlet's existing children. In Design mode, select the connected filename to switch files, or select **Open** to edit it. To disconnect, select the **Source** property label and choose **Reset value**. Disconnecting leaves the MDX file unchanged, removes its derived body content from the canvas, and preserves the designed shell with an empty Body outlet.
+#### Prepare the Content Block

-When you connect an older Content Block that has no Body outlet, Webstudio replaces its existing editable content and adds the outlet automatically.
+1. Add the Content Block and design its shell in Design mode.
+2. Place the **Body** outlet where the article body should render.
+3. Add any reusable custom content to **Templates**.
+4. Give every top-level template a unique instance name. MDX uses that name to find the template.

-In Content mode, **Source** shows the connected filename and an **Open** button so editors can identify and edit the file. Changing, binding, resetting, and disconnecting the source remain available only in Design mode.
+New Content Blocks already include a Body outlet. When you connect an older Content Block without one, Webstudio adds it automatically.

-Editors continue to use the normal Content mode controls. Their changes appear immediately on the canvas and then save to the connected file. Changes made in the file editor also update every Content Block connected to that file.
+#### Create and connect the file
+
+1. Open **Assets**, select **Create text file**, and create a file ending in `.mdx`.
+2. Select the Content Block in Design mode.
+3. Under **Properties & attributes**, select **Connect .mdx file** for **Source**.
+4. Select the file, or bind **Source** to an expression that returns an MDX Asset ID.
+5. If the Content Block already has body content, review the warning and confirm the connection. The file replaces the existing Body children.
+
+<figure>
+  <picture>
+    <source srcset="../../.gitbook/assets/create-mdx-file-dark.png" media="(prefers-color-scheme: dark)">
+    <img src="../../.gitbook/assets/create-mdx-file-light.png" alt="New text file dialog with article.mdx entered in the filename field">
+  </picture>
+  <figcaption><p>Change the default filename so that it ends in <code>.mdx</code>.</p></figcaption>
+</figure>
+
+<figure>
+  <picture>
+    <source srcset="../../.gitbook/assets/connect-content-block-mdx-dark.png" media="(prefers-color-scheme: dark)">
+    <img src="../../.gitbook/assets/connect-content-block-mdx-light.png" alt="Content Block settings with Connect .mdx file under the Source property">
+  </picture>
+  <figcaption><p>Connect the file from the Content Block's Source property.</p></figcaption>
+</figure>
+
+Select the connected filename to choose another file. Select **Open** to edit the current file. In Content mode, editors can see the filename and open it, but only a designer can connect, switch, bind, or disconnect the source.
+
+#### Edit the body in Content mode
+
+Edit the connected body with the usual Content mode controls. You can change text and supported properties, insert templates, reorder content, and delete content. Canvas changes appear immediately and then save to the MDX file.

 Component properties in Content mode are limited to authored content, such as links, media sources and alternative text, form labels and placeholders, code, and date values. Layout, dimensions, visual themes, form wiring, and interaction settings remain available only in Design mode.

-Use Markdown for headings, paragraphs, links, lists, tables, code, and other standard document content. MDX uses Webstudio elements only for content that Markdown cannot represent:
+If the file changes after a canvas edit starts but before it is saved, reload the Content Block before continuing. Webstudio keeps the local canvas state until reload and does not silently merge or overwrite either version.
+
+#### Write Markdown and MDX
+
+Write headings, paragraphs, links, lists, tables, code, images, and other standard document content as Markdown. Webstudio writes a standard element as `<ws.element ws:tag="tag">` only when its authored properties cannot be represented by Markdown. It uses `ws:name` only to insert a uniquely named top-level template:

 ```mdx
 # Product update
@@ -88,25 +125,35 @@ Regular document content stays Markdown.

 The `ws:name` value must exactly match a unique top-level instance name in the Content Block's Templates list. Missing templates show a warning in Builder and are omitted from the published site. Invalid or unsupported MDX remains editable; Builder reports the source location and renders the valid content it can recover.

-You can connect multiple Content Blocks to the same MDX file. Editing any connected occurrence updates the shared file and the other connected occurrences.
+Keep template names stable after connecting MDX files. Webstudio prevents duplicate top-level template names. Renaming or deleting a referenced template warns that connected files will not be rewritten. If you continue, update the affected `ws:name` references in the MDX files. An MCP-connected agent can preview and confirm that update across a selected group of files.

-If the file changes after a canvas edit starts but before it is saved, Builder asks you to reload. It preserves the local canvas state until reload and does not merge or overwrite either version automatically.
+#### Use frontmatter in the designed shell

-Edit frontmatter as YAML in the MDX file editor. Canvas edits update only the document body and preserve the frontmatter source, including its comments and formatting. Content-mode users with Asset access can open the MDX file from Assets to edit its frontmatter.
+Edit frontmatter as YAML in the MDX file editor. Visual body edits preserve the frontmatter source, including comments and formatting.

-To use frontmatter in the designed part of a Content Block, bind a property or text value to the Content Block's **Document** parameter. For example, bind a heading to `Document.frontmatter.title` or an image source to `Document.frontmatter.featureImage`. Direct frontmatter bindings remain part of the same MDX file and can be edited on the canvas in Content mode. Computed expressions and values supplied through another document's `$ref` remain read-only on the canvas; open the referenced file to edit referenced values.
+To use frontmatter in the designed part of a Content Block, [bind](../foundations/variables.md) a property or text value to the Content Block's **document** variable. For example, bind a heading to `document.frontmatter.title` or an image source to `document.frontmatter.featureImage.src`. Direct frontmatter bindings remain part of the same MDX file and can be edited on the canvas in Content mode. Computed expressions and values supplied through another document's `$ref` remain read-only on the canvas; open the referenced file to edit referenced values.

-New Content Blocks include a **Body** outlet. Place it anywhere inside the designed article layout: the connected file's MDX body renders there, while the surrounding instances can use frontmatter bindings. Templates stay protected and continue to control which custom instances editors may insert into the body.
+#### Use one file in repeated or shared content
+
+For a Content Block inside a Collection, bind **Source** to the current item's MDX Asset ID. Each Collection item then opens and edits its own file.
+
+You can also connect multiple Content Blocks to the same MDX file. Editing the file or any connected occurrence updates every other occurrence.
+
+When you copy a connected Content Block, page, template, or folder to another project, Webstudio copies the MDX file and the local files it references. The pasted Content Block points to those imported copies. If Webstudio cannot parse the MDX, it preserves the source file and reports that its dependencies could not be collected.

 To create another post with the same structure, duplicate the existing MDX Asset, edit the duplicate, and connect or bind the appropriate Content Block occurrence to it.

+#### Disconnect the file
+
+In Design mode, select the **Source** property label and choose **Reset value**. Disconnecting leaves the MDX file unchanged, removes its body from the canvas, and keeps the designed shell and Templates list with an empty Body outlet. If the source is bound inside a Collection, review the warning before confirming: resetting the shared Source property disconnects every Collection occurrence.
+
 ## Content Block in Content mode

 In [Content mode](../foundations/modes.md#content), you can edit existing content inside Content Blocks. But what if you want to add _new_ content?

-You can within Editable Block — region(s) on the page the designer designates as a place you can add new content from building blocks to entire sections.
+You can within Content Block — region(s) on the page the designer designates as a place you can add new content from building blocks to entire sections.

-For example, on your homepage, you change out promotions. Sometimes they are events, and other times they are products. The designer can add the Editable Block to that section on your homepage and provide you with an “Events template” and “Products template”. You can then insert instances of each template, delete them, and change out their content. The design is fully provided for you.
+For example, on your homepage, you change out promotions. Sometimes they are events, and other times they are products. The designer can add the Content Block to that section on your homepage and provide you with an “Events template” and “Products template”. You can then insert instances of each template, delete them, and change out their content. The design is fully provided for you.

 Next is how to use it.

@@ -114,7 +161,11 @@ Next is how to use it.

 On the left-hand side, there is the navigator showing you the various Content Blocks on the page.

-<figure><img src="../../.gitbook/assets/content-blocks-navigator.png" alt="Content Blocks in the navigator"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/content-blocks-navigator-dark.png">
+  <img src="../../.gitbook/assets/content-blocks-navigator-light.png" alt="Navigator with an expanded Content Block showing Templates and Content Block Body with paragraph and list children">
+</picture>
+

 You can click on them to navigate to that part of the page.

@@ -124,7 +175,8 @@ Each Content Block can have a unique set of templates you can choose from.

 On the canvas, hover where you want to insert, and the blue + button will appear. Click that, and you’ll see a list of templates provided by the designer.

-<figure><img src="../../.gitbook/assets/templates-content-mode.png" alt=""><figcaption><p>Templates the designer provided</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/templates-content-mode.png" alt="Template picker in Content mode"><figcaption><p>Templates the designer provided</p></figcaption></figure>
+

 Select the one you want, and it’ll insert an instance/copy of that template.

@@ -137,7 +189,8 @@ You can delete a direct child of the Content Block in one of two ways:
 1. The blue + button will turn into a red delete button if you hold the option/alt key on your keyboard.
 2. Select the instance in the navigator, and press delete/backspace on your keyboard.

-   <figure><img src="../../.gitbook/assets/delete-instance-content-mode.gif" alt="plus button changing to delete when holding option/alt"><figcaption><p>Hold option/alt</p></figcaption></figure>
+   <figure><img src="../../.gitbook/assets/delete-instance-content-mode.gif" alt="Content mode add button changing to delete while Option or Alt is held"><figcaption><p>Hold Option or Alt</p></figcaption></figure>
+

 {% hint style="success" %}
 You can’t delete the template itself, so you can always add it back.
@@ -12,7 +12,10 @@ The Element component is a versatile component that can represent any HTML eleme

 The Element component can be found in **Components > General**, and you can place it on your canvas by dragging and dropping it or clicking it in the Components panel.

-<figure><img src="../../.gitbook/assets/element-components-panel.png" alt="" width="278"><figcaption><p>Components panel</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with Element listed first in the expanded General group">
+</picture>

 ---

@@ -72,7 +75,10 @@ The Element component can be rendered as many HTML tags, including but not limit

 You can change the HTML tag of the Element by opening the **Settings Panel** located on the right side of the Builder.

-<figure><img src="../../.gitbook/assets/element-settings-panel.png" alt="" width="239"><figcaption><p>Settings panel</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/element-settings-panel-dark.png">
+  <img src="../../.gitbook/assets/element-settings-panel-light.png" alt="Settings panel for a paragraph element with Name, Show, Tag, ID, and Class controls">
+</picture>

 The tag dropdown shows all available HTML elements you can use. When you change the tag, the component's properties automatically update to show relevant attributes for that element type.

@@ -10,7 +10,10 @@ description: >-

 {% embed url="https://www.youtube.com/watch?v=LeE52a_EWFw" %}

-<figure><img src="../../.gitbook/assets/headslot.png" alt="Head Slot" width="375"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with Head Slot in the expanded General group">
+</picture>

 The Head Slot provides a visual interface for controlling your website's `<head>` section. Instead of writing code, you can manage meta tags, canonical URLs, and other head elements directly in the builder.

@@ -10,29 +10,28 @@ The HTML Embed component enables the direct integration of custom HTML, CSS, and

 ---

-### How to use the HTML Embed component
+## How to use the HTML Embed component

 The "HTML Embed" component can be found in Components > General, and you can place it on your canvas by dragging and dropping it or clicking it in the Components panel.

 ---

-### How to add custom code to an HTML Embed instance
+## How to add custom code to an HTML Embed instance

 You can add your custom HTML, CSS, or JavaScript code to the HTML Embed instance by selecting it and accessing its “Settings”.

 The **Code** property is also available in Content mode when the HTML Embed is inside an editable Content Block.

-#### Code
+### Code

-<figure><img src="../../.gitbook/assets/gsap.png" alt=""><figcaption></figcaption></figure>

 The "Code" section has a text area for adding your custom code. After you paste your code here, it will be rendered on the canvas. You can add anything to your site including custom widgets, third-party services, API integrations, animations, and interactive content.

-### Run Script on Canvas
+## Run script on canvas

 The "Run Script on Canvas" toggle allows you to not only render the HTML embed directly on the canvas, but also execute scripts. It will look exactly the same way as when you publish the site.

-### Client Only
+## Client only

 If your HTML embed is script-free and only includes items like SVG icons, CSS, or static HTML, you don't need this option.

@@ -40,9 +39,11 @@ For embeds with scripts that change HTML, like GSAP animations or sliders, activ

 Check out how to embed [GSAP animations](../how-tos/how-to-add-a-gsap-animation.md).

+<figure><img src="../../.gitbook/assets/gsap.png" alt="GSAP script configured in an HTML Embed"><figcaption></figcaption></figure>
+
 ---

-### How to reuse your custom code across multiple web pages
+## How to reuse your custom code across multiple web pages

 You can reuse your custom code across your project by putting it inside a Slot instance.

@@ -52,7 +53,7 @@ You can reuse your custom code across your project by putting it inside a Slot i

 Please note that any updates you make inside your slot will update all other instances of that slot.

-### Avoid creating global variables
+## Avoid creating global variables

 When using the tag, every variable you create is global by default, which can lead to unpredictable effects.\
 \
@@ -71,7 +72,7 @@ What could go wrong? 😅
 1. If you navigate away and come back to the page, the script gets executed again and you will get a syntax error: "Identifier 'a' has already been declared". This is due to the fact that const can be declared only once. You could workaround this by using `var` or `let` instead.
 2. If your logic relies on an existing variable and you don't redefine it, it will use any random value that happens to be there at a given time.

-#### Solution 1 - module
+### Solution 1 – module

 When using the module type, the script has its own scope, and the variables don't become global.

@@ -81,7 +82,7 @@ When using the module type, the script has its own scope, and the variables don'
 </script>
 ```

-#### Solution 2 - function scope
+### Solution 2 – function scope

 Use an Immediately Invoked Function Expression (IIFE) to create a function scope.

@@ -93,7 +94,7 @@ Use an Immediately Invoked Function Expression (IIFE) to create a function scope
 </script>
 ```

-### Don't use DOMContentLoaded
+## Don't use DOMContentLoaded

 The **DOMContentLoaded** event won't fire during client-side navigation between pages because, technically, the page isn't reloaded. Use the same logic you intended to write inside that event handler, and if you need to wait for an element to be rendered first, place the embed after it.

@@ -12,23 +12,28 @@ description: >-

 ---

-### How to use the Image component
+## How to use the Image component

-The "Image Component" can be found in Components > Media, and you can place it on your canvas by dragging and dropping it or clicking it in the Components panel. ![Webstudio image component](../../.gitbook/assets/image-component-overview.webp)
+The Image component is available under **Components > Media**. Drag it onto the canvas or click it to insert it at the selected location.

-#### Responsive Images
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with Image in the expanded Media group">
+</picture>
+
+### Responsive images

 Webstudio automatically generates responsive images for your website, so you don't have to worry about manually resizing and optimizing images for different devices.

 These responsive images automatically adjust their size based on the user's screen size, ensuring optimal resolution and quick loading whether the user is on a desktop monitor or a smartphone.

-#### Supported Image Formats
+### Supported image formats

 All images in Webstudio are automatically optimized and served in WebP or AVIF format, depending on the responsive image resolution and browser support. This eliminates the need for pre-optimization and extra tools to compress or convert images.

 WebP is supported by all modern browsers, including Chrome, Edge, and Firefox, while AVIF offers better compression quality and smaller file sizes but lacks support in browsers like Edge and Internet Explorer.

-#### Ensure a Stable Layout for Improved Performance
+### Ensure a stable layout for improved performance

 It is essential to ensure that your browser can calculate an image's width and height without waiting for it to load. You can do this by setting the image's width/height in the Style panel or directly in the Image instance's properties.

@@ -38,17 +43,17 @@ If a browser can't calculate an image's size, it continues rendering the page, b

 > Note: You can assess page speed using tools like [Page Speed](https://pagespeed.web.dev/). For reference, an unhinted hero image can easily decrease the page speed score from 100 to 70!

-#### Provide Aspect Ratio Upfront
+### Provide aspect ratio upfront

 In Webstudio, every image has its aspect ratio set automatically. To prevent any layout shifts on your site, it's best to set the "width" property for each image you add. This ensures that the images fit smoothly into the overall design without causing any unexpected changes in layout.

 ---

-### How to customize an Image instance's properties
+## How to customize an Image instance's properties

 You can customize the properties of an Image instance by selecting it and going to "Settings." Here is an overview of each property:

-#### Source
+### Source

 The Source property lets you link an image file from the Assets Panel to your image instance. To add an image to your instance, click "Choose source" and select an image from the Assets Panel.

@@ -58,7 +63,7 @@ You can also drag a single image from the Assets panel directly onto the canvas.
 Webstudio inserts a new Image component and selects the dragged asset as its
 source.

-#### Width/Height
+### Width and height

 The "width" and "height" properties define your image's initial display size in pixels and its aspect ratio. However, the final rendered image size is subject to CSS rules and layout constraints.

@@ -66,17 +71,17 @@ This means that if you set the width or height of an image in the Style panel or

 The Width/Height properties are prioritized in some cases. For instance, if you only set the image's height in the Style panel, the width will be automatically determined from the Image Instance's "Width" property, and vice versa. This maintains the aspect ratio while adjusting the image's size with your specified values.

-#### Alternative Text (alt)
+### Alternative text (alt)

 The "alt" property provides alternative text for the image. This text is vital for accessibility purposes, as it describes the image's content in case the image cannot be seen.

-#### Loading
+### Loading

 The "Loading" property specifies how the browser handles image loading. You can set it to "Lazy" to load the image only when it comes into the viewport or "Eager" to load it immediately.

 Here's a helpful tip: If you have an image in the initial viewport, always set it to "Eager." This way, the image gets priority, and it loads quickly, improving your site's overall performance.

-#### Optimize
+### Optimize

 The "optimize" property lets you control if the image will go through the image transformation process including resizing, converting, and compressing it. This setting works on first and third-party images (e.g., images that come from a headless CMS). In rare scenarios, the user may want to turn this off.

@@ -26,16 +26,16 @@ You can customize the properties of a Link instance by selecting it and going to

 ### Href

-<figure><img src="../../.gitbook/assets/link-href-property.avif" alt=""><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/link-href-property.avif" alt="Link settings with the Href property available for a destination"><figcaption></figcaption></figure>

 The "href" property determines what the Link instance will lead to, such as a URL, page, phone, attachment, or email address.

 1. **URL**: In its most common form, the "href" property references a URL, linking to another website or page.
 2. **Page**: You can link to all of your pages within your site here. You can also link to specific sections within those pages. To link to a section on a page, first go to the section and fill out the `ID` field in Settings. Then go back to the link, select the page, and then in the next dropdown select the `ID` you just created. Like this:

-   <div align="center"><figure><img src="../../.gitbook/assets/section-id.png" alt="" width="375"><figcaption><p>First add the ID to the section you want to link to</p></figcaption></figure></div>
+   <div align="center"><figure><img src="../../.gitbook/assets/section-id.png" alt="Section settings with an ID entered as the anchor destination" width="375"><figcaption><p>First add the ID to the section you want to link to</p></figcaption></figure></div>

-   <div align="center"><figure><img src="../../.gitbook/assets/link-to-section.png" alt="" width="375"><figcaption><p>Then add a page link and select the section.</p></figcaption></figure></div>
+   <div align="center"><figure><img src="../../.gitbook/assets/link-to-section.png" alt="Link destination picker with a section selected on the current page" width="375"><figcaption><p>Then add a page link and select the section.</p></figcaption></figure></div>

 3. **Email**: When you specify an email address as the 'href' value, the link opens the user's default email client (such as Gmail) with the designated email address pre-filled.
 4. **Phone**: If you set the "href" property to a phone number, the link becomes a prompt for users to initiate phone calls directly from their devices.
@@ -43,7 +43,7 @@ The "href" property determines what the Link instance will lead to, such as a UR

 ### Target

-<figure><img src="../../.gitbook/assets/link-target-property.avif" alt=""><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/link-target-property.avif" alt="Link settings with the Target property options open"><figcaption></figcaption></figure>

 You can use the "Target" property to modify a link instance's behavior and define how linked content is displayed.

@@ -71,7 +71,7 @@ You can add any Webstudio component inside a Link element to make it clickable

 When using links for navigation and wanting to highlight the current page, the link component has a "Local Link" state in every style source.

-<figure><img src="../../.gitbook/assets/link-local-link-state.png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/link-local-link-state.png" alt="Style sources showing the current-page state for a local link"><figcaption></figcaption></figure>

 ## Related

@@ -52,7 +52,7 @@ Setting the List Style Type allows you to define the appearance of the bullet po

 ### How to customize a List instance's properties in Webstudio

-<figure><img src="../../.gitbook/assets/list-component-properties.avif" alt=""><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/list-component-properties.avif" alt="List settings showing ordered and unordered list properties"><figcaption></figcaption></figure>

 You can customize a List’s properties by selecting it and going to Settings. Lists come with three base properties: Ordered, Reserved, and Start. To add additional properties, click the “+” next to Properties and add a new property.

@@ -24,19 +24,20 @@ Data variables defined on the Global Root are accessible within Slots, while tho

 ---

-### How to use Slot Component
+## How to use Slot component

 Here is the process for creating and reusing Slot instances:

-#### Creating a Slot instance
+### Creating a Slot instance
+
+![Slot component and its source content on the canvas](../../.gitbook/assets/slot-component-overview.png)

-&#x20;![create a slot in Webstudio](../../.gitbook/assets/slot-component-overview.png)

 1. You can find the Slots component in the “Components Panel.”
 2. Drag “Slot” from the Components Panel onto your canvas to create a Slot instance. Alternatively, you can add it to the currently selected instance with a click.
 3. Add other instances from the Components Panel into the Slot instance to populate it.

-#### Reusing a Slot instance
+### Reusing a Slot instance

 Once you have a Slot on the canvas you can re-use it by simply copying and pasting it anywhere in your project.

@@ -61,7 +62,7 @@ occurrence to change.

 ---

-### Conclusion
+## Conclusion

 With Slots you can re-use content across your site and sync the changes you make to them.

@@ -9,7 +9,7 @@ The Vimeo component for Webstudio allows you to embed Vimeo videos into your sit

 ---

-### Benefits of Vimeo
+## Benefits of Vimeo

 We have picked Vimeo to be Webstudio’s first video component for the following reasons:

@@ -21,19 +21,24 @@ We have picked Vimeo to be Webstudio’s first video component for the following

 ---

-### How to use the Vimeo component in Webstudio
+## How to use the Vimeo component in Webstudio

 You can find the Vimeo Component in the Components Panel in the Media Section. Here is how you can add and use the component on your site:

-#### Adding the Vimeo component to your canvas
+### Adding the Vimeo component to your canvas
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with Vimeo in the expanded Media group">
+</picture>

-![Vimeo to your canvas](../../.gitbook/assets/vimeo-component-step-1.avif)

 1. You can find the Vimeo component in the “Components Panel” in the Media section.
 2. Add the component by dragging and dropping it to the canvas or with a click to put it inside the selected instance.
 3. Once you have the component on your canvas, you can head to Settings on the right to add your video URL and make other changes.

-![Vimeo background settings](../../.gitbook/assets/vimeo-component-properties.avif)
+![Vimeo component properties in Settings](../../.gitbook/assets/vimeo-component-properties.avif)
+
 ## Sub-components

 The Vimeo component contains three child instances visible in the Navigator:
@@ -43,20 +48,21 @@ The Vimeo component contains three child instances visible in the Navigator:
 | **Preview Image** | The thumbnail shown before playback. Replace it with your own image in Settings. |
 | **Spinner** | The loading indicator shown while the video buffers. Hide it via the **Show** toggle in Settings. |
 | **Play Button** | Contains a Box and a Play Icon. Style the Box (background, border-radius, etc.), swap the icon SVG via the HTML Embed inside, or hide the entire button via the **Show** toggle for background video use. |
-#### Modifying the Preview Image
+### Modifying the preview image

 1. Inside the Vimeo Component, you will find three instances- the Preview Image, Spinner and Play Button. These instances define the primary look of the embedded video player.
 2. You can add a preview image to your video by selecting the “Preview Image” instance and choosing an image source in the “Properties” section.

 ---

-### How to customize the Vimeo instance's properties
+## How to customize the Vimeo instance's properties

 The Vimeo component comes with several properties that you can use to customize your video player. These properties appear in the Settings panel to the right of the canvas when your Vimeo component is selected.

 Here’s how you can use the following properties:&#x20;

-![Vimeo background properties](../../.gitbook/assets/vimeo-instance-properties.avif)
+![Vimeo properties in the Settings panel](../../.gitbook/assets/vimeo-instance-properties.avif)
+

 - **Show Preview**\
  Toggle this property on to render the preview image from Vimeo rather than the static image in Webstudio. This property is turned off by default because rendering the Vimeo preview requires making an API call which can slow down the speed of your page.
@@ -79,7 +85,7 @@ Here’s how you can use the following properties:&#x20;
 - **Other Properties**\
  You can customize your Vimeo component further by adding [other properties](https://developer.vimeo.com/player/sdk/embed) that are not listed in the "Properties" section by default.

-### Customizing the Play Button and Spinner
+## Customizing the play button and spinner

 The Vimeo component includes customizable child instances:

@@ -92,7 +98,7 @@ The Vimeo component includes customizable child instances:
   - Change the Play Icon's color via typography color on its parent
   - Hide the Play Button using the "Show" toggle for background video use

-### Hiding Player Elements
+## Hiding player elements

 For background videos or custom player designs, you may want to hide default elements:

@@ -8,24 +8,26 @@ description: "The XML Node\_is used to create\_an XML document, such as a sitema
 Webstudio automatically generates a sitemap for static pages such as Home and About. If you are integrating with a CMS, you can use this component to create a sitemap for CMS data.
 {% endhint %}

-<figure><img src="../../.gitbook/assets/xml-component.png" alt=""><figcaption><p>Will display when Document Type is set to "XML"</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/xml-component.png" alt="XML Node component available for an XML page"><figcaption><p>The component appears when Document type is XML</p></figcaption></figure>

-### How to use the XML Node component
+
+## How to use the XML Node component

 1.  Go to Page Settings > Document Type and select XML from the dropdown&#x20;

-    <figure><img src="../../.gitbook/assets/page-settings-xml-doc-type.png" alt="Page Settings Document Type to XML"><figcaption></figcaption></figure>
+    <figure><img src="../../.gitbook/assets/page-settings-xml-doc-type.png" alt="Page Settings with Document type set to XML"><figcaption></figcaption></figure>
+

 2.  Go to Components > XML and add XML Node (this component won’t show until Step 1 is completed)
 3.  Set the tag and text content (e.g., “loc” and “https://example.com)

-### Tips
+## Tips

 - XML Nodes can be nested within each other
 - Use [Collection](collection.md) to iterate over a list of data
 - A sitemap skeleton is available in the Marketplace

-### Including the static sitemap
+## Include the static sitemap

 While you can use the autogenerated sitemap for static pages and create a separate sitemap for dynamic pages, you can also combine the two.

@@ -36,7 +38,8 @@ To include the static sitemap data in your custom sitemap, follow these steps:
 3. Set the page path to /sitemap.xml. This will override the default sitemap.
 4. Fetch the static data by clicking Create Variable > System Resource (Type) > Sitemap (Resource)&#x20;

-   <figure><img src="../../.gitbook/assets/static-sitemap-data.png" alt=""><figcaption></figcaption></figure>
+   <figure><img src="../../.gitbook/assets/static-sitemap-data.png" alt="Sitemap System Resource selected in Dynamic data"><figcaption></figcaption></figure>
+

 5. Use a [Collection](collection.md) to iterate over the static sitemap data

@@ -7,7 +7,10 @@ icon: youtube

 # YouTube

-<figure><img src="../../.gitbook/assets/youtube-component.png" alt="YouTube Component in Webstudio Add Panel"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with YouTube in the expanded Media group">
+</picture>

 While YouTube offers embed codes, the YouTube component enables a much better experience, which is why it’s the recommended way to add YouTube videos to your site.

@@ -6,34 +6,34 @@ description: >-

 # 🛠️ Anatomy of the Webstudio builder

---
-
 {% embed url="https://www.youtube.com/playlist?list=PL4vVqpngzeT4Bfs_D25xNi_qNMY99R928" %}
 Webstudio 101 Playlist
 {% endembed %}

---
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/builder-overview-dark.png">
+  <img src="../../.gitbook/assets/builder-overview-light.png" alt="Webstudio Builder with the Navigator on the left, canvas in the center, and Style panel on the right">
+</picture>

 ## Canvas

-The canvas provides a visual representation of the website you are creating. After adding components from the Components Panel, you can arrange and style their instances on the canvas.
-
-<figure><img src="../../.gitbook/assets/canvas.png" alt="Canvas"><figcaption></figcaption></figure>
-
---
+The canvas provides a visual representation of the website you are creating. After adding components from the Components panel, you can arrange and style their instances on the canvas.

 ## Navigator

 The Navigator Panel is a hierarchical overview of all instances on your page. It displays the website’s structure, showing the nesting and relationships between different instances. You can select the instance of any component inside your Project by clicking it on the canvas or inside the navigator.

-### Renaming Instances
+### Rename instances

 Double-click any instance in the Navigator to rename it. Use semantic names like "Hero Section" or "Contact Form" to make your project structure easier to understand and maintain.
 In the bottom half of the navigator, you will find the CSS Preview section, which is a real-time preview of the CSS styles applied to your selected instance.

-<figure><img src="../../.gitbook/assets/navigator.png" alt="" width="373"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/navigator-panel-dark.png">
+  <img src="../../.gitbook/assets/navigator-panel-light.png" alt="Navigator panel showing Global root, Body, and a nested Content Block instance">
+</picture>

-### Global Root
+### Global root

 In the Navigator is the Global Root, the highest level of the page. Changes made to it apply to every page. It’s useful for setting global styles, such as font size and line height, and defining [CSS variables](css-variables.md) so they are accessible on every instance on every page. Changing the font size on the root affects all CSS properties that use REM, as this unit is relative to the root font size. For example, `1rem` outputs as `1 x root font size`.

@@ -41,9 +41,10 @@ In the Navigator is the Global Root, the highest level of the page. Changes made
 Global Root uses the`:root` [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) under the hood.
 {% endhint %}

-<figure><img src="../../.gitbook/assets/global-root.png" alt="Global Root"><figcaption><p>Global Root</p></figcaption></figure>
-
---
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/navigator-panel-dark.png">
+  <img src="../../.gitbook/assets/navigator-panel-light.png" alt="Navigator with Global root above Body and the page instance tree">
+</picture>

 ## Breakpoints

@@ -57,7 +58,10 @@ You can create custom breakpoints with any media query condition – not just wi
 Adding too many breakpoints or mixing and matching `min-width` and `max-width` will make maintenance difficult. The default breakpoints suffice more in the majority of use cases.
 {% endhint %}

-<figure><img src="../../.gitbook/assets/breakpoints.png" alt="Webstudio Breakpoints"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/breakpoints-dark.png">
+  <img src="../../.gitbook/assets/breakpoints-light.png" alt="Breakpoint menu listing desktop, tablet, and mobile breakpoint conditions">
+</picture>

 By defining how components should behave at different screen sizes, you can ensure your website looks great on various devices, including desktops, tablets, and smartphones.

@@ -65,23 +69,27 @@ By defining how components should behave at different screen sizes, you can ensu
 When you select a breakpoint, such as 991, you’ll notice that the canvas is sized to 768. This is intentional. The goal is to style for the minimum (or maximum, if using min-width) to ensure all design issues are addressed at the "extreme" end of that breakpoint. When the viewport changes to 767, the next breakpoint is triggered.
 {% endhint %}

---
-
-## Components Panel
+## Components panel

 The Components Panel contains a list of all available [components](../core-components/) that you can add to your Webstudio Project. You can do this by clicking the components in the panel or dragging and dropping them on the canvas.

 Components are grouped into sections like General, Text, Media, Forms, and [Radix](../radix/). For example, the Text section has all typography-related components, while the Form section nests the building blocks of a form.&#x20;

-<figure><img src="../../.gitbook/assets/components.png" alt="Add components" width="279"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/components-panel-dark.png">
+  <img src="../../.gitbook/assets/components-panel-light.png" alt="Components panel with a search field and expanded General, Typography, and Media groups">
+</picture>

---
-
-## Assets Panel
+## Assets panel

 The Assets Panel is the second panel to the left of your canvas, and this is where all the static files are stored. You can upload, organize, and manage project assets inside this panel before using them on the canvas.

-### Asset Types
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/assets-panel-dark.png">
+  <img src="../../.gitbook/assets/assets-panel-light.png" alt="Assets panel with search, filter and sort controls above folders and files">
+</picture>
+
+### Asset types

 The Assets Panel supports various file types organized by category:

@@ -92,7 +100,7 @@ The Assets Panel supports various file types organized by category:

 This list is not exhaustive – Webstudio supports many additional file formats.

-### Filtering and Sorting
+### Filter and sort

 Use the filter dropdown to show only specific asset categories (Images, Fonts, Documents, or All). Assets can be sorted by:

@@ -100,7 +108,7 @@ Use the filter dropdown to show only specific asset categories (Images, Fonts, D
 - **Date** – Newest or oldest first
 - **Size** – Largest or smallest first

-### Asset Details
+### Asset details

 Click on any asset to view its details panel, which shows:

@@ -110,7 +118,7 @@ Click on any asset to view its details panel, which shows:
 - **File size** – Size of the asset file
 - **Uses** – Number of places the asset is used in your project

-### Asset Actions
+### Asset actions

 - **Download** – Download the original asset file to your computer (Pro plan required)
 - **Review & Delete** – When an asset is in use, shows where it's used before confirming deletion. Unused assets can be deleted directly.
@@ -124,32 +132,34 @@ Click on any asset to view its details panel, which shows:
 Assets that are currently used in your project will show a settings gear icon. Attempting to delete them will display a list of all usages so you can review before confirming.
 {% endhint %}

---
-
-## Pages Panel
+## Pages panel

 The Pages Panel offers an overview of the website’s page structure and hierarchy, and it is the last panel on the left side of your canvas, under the Components and Assets Panels.

 You can use this panel to add new pages to your Webstudio site, set the homepage, rename existing ones, and configure fields for social sharing and search engines.

-### Page Folders
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/pages-panel-dark.png">
+  <img src="../../.gitbook/assets/pages-panel-light.png" alt="Pages panel with Home and an expanded Blog folder containing Post, Author, and Posts pages">
+</picture>
+
+### Page folders

 Organize your pages into collapsible folders for better project management. Right-click in the Pages Panel to create a new folder, then drag pages into it. Folders help keep large projects organized and make navigation easier.

---
-
-## Style Panel
+## Style panel

 The Style Panel is located to the right of the canvas, and you can use it to customize the appearance and layout of a selected instance. It offers access to all CSS properties, visually.

-<figure><img src="../../.gitbook/assets/style-panel.png" alt="Style Panel" width="256"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/style-panel-dark.png">
+  <img src="../../.gitbook/assets/style-panel-light.png" alt="Style panel showing style sources, layout, grid child, spacing, and size controls">
+</picture>

 There are three methods for adding styles:

 1.  Local - By default, the Local icon is active, meaning any styles you apply to that instance are for that instance only. The dot in the middle of the Local icon indicates that it has styles, whereas no dot indicates that there are no styles applied, making it easy to identify which ones have styles applied.

-    <img src="../../.gitbook/assets/style-sources.png" alt="Local style source" data-size="original">
-
 2.  [CSS variables](css-variables.md) - Instead of pasting in your colors, sizes, and other styles, you can create a variable for each style and access the variables in each input field. For example, you can define a variable called "color-primary," and in your border color field, you can enter the variable name instead of the color itself.
 3.  [Tokens](design-tokens.md) - These enable reusing groupings of styles across your site. You can either create a new Token and apply styles to it or start with Local and convert it to a Token. Tokens are typically comprised of CSS variables and one-off styles.

@@ -168,9 +178,7 @@ The style input labels change colors indicating there is a style present.
 The order of tokens in the Style Source Input matters. When multiple Tokens have a value for the same property, Tokens toward the end of the list will overwrite Tokens toward the beginning of the list.
 {% endhint %}

---
-
-## Settings Panel
+## Settings panel

 The Settings Panel is on the right side of your canvas. You can use this panel to access and edit component-specific properties (such as ID or class) and [Data variables](variables.md) for a selected instance, enabling you to store reusable content and fetch APIs — a building block of [CMS](cms.md).

@@ -180,9 +188,10 @@ The Settings Panel is on the right side of your canvas. You can use this panel t

 [Modes](modes.md) change the Builder's behavior, such as previewing your site without distractions.

-<figure><img src="../../.gitbook/assets/builder-modes.png" alt="Mode switcher showing Design and Content modes"><figcaption></figcaption></figure>
-
---
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/builder-modes-dark.png">
+  <img src="../../.gitbook/assets/builder-modes-light.png" alt="Mode menu with Design and Content options and their keyboard shortcuts">
+</picture>

 ## Hide UI

@@ -192,23 +201,22 @@ Use Hide UI when you want more canvas space while designing, editing content, or

 You can enable Hide UI from **Menu > View > Hide UI** or with `⌘ + \` on Mac and `Ctrl + \` on Windows.

-<figure><img src="../../.gitbook/assets/builder-hide-ui-menu.png" alt="Builder View menu showing the Hide UI option and keyboard shortcut"><figcaption><p>Hide UI in the View menu</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/builder-hide-ui-menu-dark.png">
+  <img src="../../.gitbook/assets/builder-hide-ui-menu-light.png" alt="Builder menu with the View submenu open and Hide UI available with its keyboard shortcut">
+</picture>

---
-
-## Share Dialog
+## Share dialog

 The [Share Dialog](share-links.md) allows you to create shareable personal links to your Project with varying permissions.

 ---

-## Publish Dialog
+## Publish dialog

 The [Publish Dialog](publishing-and-custom-domains.md) enables you to add a custom domain, publish to Staging and/or your custom domain, and [export your Project](../self-hosting/).

-{% hint style="info" %}
-Publishing currently takes around 45 seconds. During publishing, your Project is built into a JavaScript app and deployed to 300+ servers around the world.
-{% endhint %}
+Publishing builds and deploys the current Project. Keep the Publish dialog open to follow its status and review any reported errors.

 ## Related

@@ -6,7 +6,11 @@ description: Upload and manage images, fonts, and other files used in your proje

 The Assets panel is located on the left side of the builder. It stores all static files used in your project — images, fonts, documents, and more. Upload files here and then reference them in instances and styles throughout your site.

-<figure><img src="../../.gitbook/assets/assets-panel.png" alt="Assets panel showing uploaded images with search and filter controls"><figcaption><p>The Assets panel</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/assets-panel-dark.png">
+  <img src="../../.gitbook/assets/assets-panel-light.png" alt="Assets panel with search, filter and sort controls above folders and files">
+</picture>
+

 ## Supported file types

@@ -47,14 +51,22 @@ index them immediately.

 You can open uploaded `txt`, `csv`, `md`, `mdx`, `js`, `css`, `json`, `html`, `xml`,
 and `svg` assets in the same editor. Syntax highlighting follows the file type;
-unsupported text types use plain text. Markdown files also provide formatting
-controls and a preview.
+unsupported text types use plain text. Markdown and MDX files also provide
+formatting controls and a preview.

 MDX files use the same Markdown document features and additionally support
 Webstudio elements for content that Markdown cannot represent. Rename a `.md`
 file to `.mdx` to enable MDX parsing. Webstudio does not rewrite the file while
 renaming it; invalid MDX remains editable and reports source-located errors.

+<figure>
+  <picture>
+    <source srcset="../../.gitbook/assets/mdx-editor-preview-dark.png" media="(prefers-color-scheme: dark)">
+    <img src="../../.gitbook/assets/mdx-editor-preview-light.png" alt="MDX editor showing frontmatter and Markdown source beside the rendered preview">
+  </picture>
+  <figcaption><p>Edit MDX source and review its rendered preview side by side.</p></figcaption>
+</figure>
+
 Edits save when the editor loses focus or when you press `Command + S` on
 macOS, `Ctrl + S` on Windows, or `Command/Ctrl + Enter`. Edit the complete
 filename in Asset settings to rename a text file or change its format. When you
@@ -70,7 +82,9 @@ Converting an empty text file to `.json` initializes it with an empty object.
 Markdown, MDX, and JSON files in Assets can be the source of truth for a site. The
 Content Engine reads their structured fields, queries the files, and resolves
 links between them. See [Content Engine](content-engine.md) for the supported
-file structure and a complete article workflow.
+file structure and a complete article workflow. Connect an MDX file to a
+[Content Block](../core-components/content-block.md#store-content-in-an-mdx-file)
+when editors should update its body visually in Content mode.

 ## Organizing assets with folders

@@ -125,7 +139,11 @@ Folders are included in the current search and sort order.

 Hover any asset and click the gear icon to open its detail panel:

-<figure><img src="../../.gitbook/assets/assets-detail.png" alt="Asset detail panel showing name, description, dimensions, MIME type, uses, and ID"><figcaption><p>Asset detail panel</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/assets-detail-dark.png">
+  <img src="../../.gitbook/assets/assets-detail-light.png" alt="Asset settings showing file size, type, dimensions, usage count, dates, name, folder, description, and ID">
+</picture>
+

 - **File size** and **MIME type**
 - **Dimensions** and **Aspect ratio** (images only)
@@ -167,7 +185,8 @@ Builder.

 ## Related

- [Content Engine](content-engine.md) – Build sites from Markdown and JSON files in Assets
+- [Content Engine](content-engine.md) – Build sites from Markdown, MDX, and JSON files in Assets
+- [Content Block](../core-components/content-block.md) – Edit an MDX document visually in Content mode
 - [Anatomy of the builder](anatomy-of-the-webstudio-builder.md) – Overview of all builder panels
 - [Image](../core-components/image.md) – Display images from assets or external URLs
 - [Commands & search](commands-and-search.md) – Quickly find and delete unused assets
@@ -43,7 +43,10 @@ Each breakpoint can override styles inherited from the previous one in the casca
 3. Set a **min-width** or **max-width** value, or choose a **media condition** (see below).
 4. Give it a label.

-<figure><img src="../../.gitbook/assets/breakpoints-edit.png" alt="Breakpoint edit dialog showing min-width and max-width fields"><figcaption><p>Editing a breakpoint</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/breakpoints-edit-dark.png">
+  <img src="../../.gitbook/assets/breakpoints-edit-light.png" alt="Breakpoints dialog showing names, minimum or maximum widths, and custom conditions">
+</picture>

 ## Editing and deleting breakpoints

@@ -54,7 +54,8 @@ The Address Bar enables previewing Dynamic Pages in the editor by entering param

 For the Dynamic Path `/post/:slug`, you would enter a slug value that exists in the CMS, such as `hello-world`.

-<figure><img src="../../.gitbook/assets/address-bar.png" alt="Address Bar with hello-world"><figcaption><p>Entering "hello-world" as a test value</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/address-bar.png" alt="Address bar with hello-world entered as the dynamic slug preview value"><figcaption><p>Entering hello-world as a test value</p></figcaption></figure>
+

 {% hint style="danger" %}
 The static part of the URL (in this case, `/post/`) is already in the Address Bar and should not be included when adding the test value.
@@ -120,9 +121,7 @@ While we do our best to verify the supported features, we may make mistakes in o

 While most CMS field types seamlessly map to Webstudio components (e.g., Plain Text → Heading), rich text may not, depending on how the CMS stores/delivers it.

-**Currently, Webstudio supports rich text if it's delivered in HTML or Markdown format.** In the future, we will support rich text regardless of the format delivered by adding conversion libraries for each CMS's flavor of rich text. For example, we'll automatically convert AST to HTML. Refer to [this issue](https://github.com/webstudio-is/webstudio/issues/3398) for more information.
-
-In the meantime, advanced users can set up a proxy on Cloudflare Workers to convert rich text to HTML. However, this is outside the scope of Webstudio's support.
+Webstudio renders rich text delivered as HTML or Markdown. If a CMS returns a proprietary AST or another structured rich-text format, convert it to HTML or Markdown before binding it in Webstudio. This conversion can happen in the CMS, its API layer, or a proxy.

 Rich text in the form of HTML can be bound to the [Content Embed Component](../core-components/content-embed.md), and Markdown can be bound to the [Markdown Embed Component](../core-components/markdown-embed.md).

@@ -142,7 +141,8 @@ cmsData.data[0].id ? 200 : 404;

 This example looks for the ID of a record. If it's there, output `200` (found!) otherwise `404` (not found).

-<figure><img src="../../.gitbook/assets/cms-dynamic-404-status-code.png" alt="Status Code field in Page Settings with expression bound"><figcaption><p>Binding an expression to the Status Code field in Page Settings</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/cms-dynamic-404-status-code.png" alt="Status code field in Page settings with an expression bound"><figcaption><p>Binding an expression to the status code</p></figcaption></figure>
+

 {% hint style="info" %}
 The exact key to look for will depend on your CMS, but think of something that will always be there if the post/record is found (slug, ID, title).
@@ -158,7 +158,8 @@ Add a component (e.g. a Box) to the page that contains your 404 message. Set its

 When this evaluates to `true`, the 404 content is shown.

-<figure><img src="../../.gitbook/assets/cms-dynamic-404-show-404-content.png" alt="Box component with Show condition set to !cmsData.data[0].id"><figcaption><p>Setting the Show condition on the 404 content Box</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/cms-dynamic-404-show-404-content.png" alt="Box component with a Show condition for missing CMS data"><figcaption><p>Setting the Show condition on the 404 content</p></figcaption></figure>
+

 {% hint style="info" %}
 To reuse an existing custom 404 page design without rebuilding it, [add a Slot](../core-components/slot.md) and select your 404 page's content as the slot source. This keeps the 404 UI in one place and lets you reuse it across any dynamic page.
@@ -174,7 +175,8 @@ cmsData.data[0].id;

 This hides the regular content when there is no data, avoiding an empty-looking page.

-<figure><img src="../../.gitbook/assets/cms-dynamic-404-show-regular-content.png" alt="Box component with Show condition set to cmsData.data[0].id"><figcaption><p>Setting the Show condition on the regular content Box</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/cms-dynamic-404-show-regular-content.png" alt="Box component with a Show condition for available CMS data"><figcaption><p>Setting the Show condition on regular content</p></figcaption></figure>
+

 ## Alternative: redirect instead of showing 404 content

@@ -12,11 +12,14 @@ Commands & search speeds up the building process and introduces new shortcuts.

 **Open Commands & search with ⌘ + K (Control + K for Windows).**

-<figure><img src="../../.gitbook/assets/commands-search.png" alt="Commands and search dialog open with results listed"><figcaption><p>Commands &amp; search</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/commands-search-dark.png">
+  <img src="../../.gitbook/assets/commands-search-light.png" alt="Commands and search dialog listing Builder commands and their keyboard shortcuts">
+</picture>

 {% embed url="https://youtu.be/ofUP0Uc_ttY" %}

-### Actions
+## Actions

 - Add components
 - Search instances by name – find any instance in your project
@@ -40,15 +43,15 @@ Commands & search speeds up the building process and introduces new shortcuts.
  - Delete Unused CSS variables – Remove CSS custom properties that are no longer used.
  - All other [keyboard shortcuts](shortcuts.md)

-### Secondary Actions with Tab
+## Secondary actions with Tab

 Some items in the Commands Panel have secondary actions. Press **Tab** to access them. For example, when searching pages, you can press Tab and arrow to "Settings" to go directly to that page's settings.

-### Find Forgotten Shortcuts
+## Find forgotten shortcuts

 If you forget a shortcut like renaming an instance, search for the action (e.g., "edit instance label") and the Commands Panel will show the shortcut so you can learn it.

-### Group Counters
+## Group counters

 Each category in the Commands Panel shows a counter indicating how many items it contains, helping you quickly understand the scope of your project.

@@ -1,18 +1,18 @@
 ---
-description: Query Markdown and JSON Assets with the Content Engine.
+description: Query Markdown, MDX, and JSON Assets with the Content Engine.
 ---

 <!-- Generated from the Content Engine schemas and shared CLI documentation. Do not edit directly. -->

 # Content Engine reference

-Assets resources query Markdown and JSON files stored in the Assets panel. The Builder and Webstudio MCP use the same structured query contract.
+Assets resources query Markdown, MDX, and JSON files stored in the Assets panel. The Builder and Webstudio MCP use the same structured query contract.

 ## MCP workflow

 Use these tools in order when creating or changing an Assets resource:

-1. Call `get-asset-field-catalog` to inspect standard fields and the fields currently observed in Markdown frontmatter and JSON files.
+1. Call `get-asset-field-catalog` to inspect standard fields and the fields currently observed in Markdown or MDX frontmatter and JSON files.
 2. Call `validate-asset-query` to check the query structure, field paths, operators, and bounded operation counts.
 3. Call `preview-asset-query` with concrete values and inspect its results and diagnostics.
 4. Save the query with `create-assets-resource` or `update-assets-resource`.
@@ -22,7 +22,7 @@ Omit `query` when creating a resource to use the default many-result query for a

 ## Fields

-Every asset has the standard fields below. Markdown frontmatter and JSON root fields appear under `properties`, for example `properties.slug` or `properties.author.name`. The field catalog reports their observed types, occurrence counts, optionality, and mixed-type state. A JSON content file must contain an object at its root.
+Every asset has the standard fields below. Markdown or MDX frontmatter and JSON root fields appear under `properties`, for example `properties.slug` or `properties.author.name`. The field catalog reports their observed types, occurrence counts, optionality, and mixed-type state. A JSON content file must contain an object at its root.

 | Field | Observed type |
 | --- | --- |
@@ -109,7 +109,7 @@ Choose `fields` and disable `includeMetadata` when the page needs only selected

 ## Asset reference metadata

-A plain local asset path in Markdown frontmatter or JSON properties keeps the backward-compatible URL string result. Wrap the path in an exact `$ref` object only when consumers need structured Asset Manager metadata:
+A plain local asset path in Markdown or MDX frontmatter, or in JSON properties, keeps the backward-compatible URL string result. Wrap the path in an exact `$ref` object only when consumers need structured Asset Manager metadata:

 ```yaml
 featureImage:
@@ -143,9 +143,9 @@ External URLs remain ordinary strings. Existing local path strings also keep the
 | `none` | Returns no file content. Use this for listings and any query that only needs fields or metadata. |
 | `full` | Embeds the complete UTF-8 file content in the content database. `maxBytes` defaults to 1 MiB and cannot be set higher. The query fails if a selected file is larger. |
 | `range` | Embeds a byte range selected by `offset` and `length` in the content database. `length` cannot exceed 256 KiB. |
-| `markdown-body-ref` | Stores a reference to a Markdown body. Webstudio filters and paginates first, then reads only the selected bodies from Assets. `maxBytes` defaults to 1 MiB and cannot be set higher. The query fails if a selected source file is larger. |
+| `markdown-body-ref` | Stores a reference to a Markdown or MDX body. Webstudio filters and paginates first, then reads only the selected bodies from Assets. `maxBytes` defaults to 1 MiB and cannot be set higher. The query fails if a selected source file is larger. |

-Returned content has `encoding` and `text`. A range also reports its `offset`, returned `length`, and total file size. Use `markdown-body-ref` for article pages. It keeps article bodies out of the published content database and resolves relative Markdown links when the selected body is loaded.
+Returned content has `encoding` and `text`. A range also reports its `offset`, returned `length`, and total file size. Use `markdown-body-ref` for Markdown or MDX article pages. It keeps article bodies out of the published content database and resolves relative links when the selected body is loaded.

 ## Preview diagnostics

@@ -168,7 +168,7 @@ Only `database.usedBytes` counts toward `database.maxBytes`. Do not add the quer
 | `artifacts` | Optional query and merged compiled artifacts used by detailed Builder diagnostics. |
 | `unresolved` | Optional query result before document references are resolved. It helps inspect the authored `$ref` values behind resolved output. |

-If the merged database approaches its limit, remove duplicate reachable resources first. Then remove unused output fields or narrow the candidate documents. Prefer `markdown-body-ref` over embedded `full` content for Markdown articles.
+If the merged database approaches its limit, remove duplicate reachable resources first. Then remove unused output fields or narrow the candidate documents. Prefer `markdown-body-ref` over embedded `full` content for Markdown or MDX articles.

 ## Document references

@@ -178,7 +178,7 @@ A document reference is an exact object with one string field:
 { "$ref": "<relative-path>[#<fragment>]" }
 ```

-Markdown references can appear in YAML frontmatter. JSON references can appear anywhere in the document. Either format can reference Markdown or JSON. References do not run inside a Markdown body.
+Markdown and MDX references can appear in YAML frontmatter. JSON references can appear anywhere in the document. Any format can reference Markdown, MDX, or JSON. References do not run inside a Markdown or MDX body.

 | Reference | Inserted value |
 | --- | --- |
@@ -210,7 +210,7 @@ Resolve paths relative to the file containing the reference. JSON Pointer uses `

 | Limit | Value |
 | --- | --- |
-| Markdown frontmatter | 64 KiB |
+| Markdown/MDX frontmatter | 64 KiB |
 | Frontmatter nesting depth | 8 |
 | Frontmatter fields | 256 |
 | Frontmatter string | 16 KiB |
@@ -1,10 +1,10 @@
 ---
-description: Create a file-based blog with Markdown, Assets queries, and dynamic pages.
+description: Create a file-based blog with Markdown or MDX, Assets queries, and dynamic pages.
 ---

 # 📚 Content Engine

-Webstudio's Content Engine turns Markdown and JSON files in Assets into content
+Webstudio's Content Engine turns Markdown, MDX, and JSON files in Assets into content
 you can query and bind in the visual editor. The files remain the source of
 truth, including their filenames, folders, metadata, and relative links. You
 can move the same files between projects or use them outside Webstudio without
@@ -16,15 +16,12 @@ This guide creates a blog overview at `/blog` and one dynamic article page at
 To see the finished setup first, start with the
 [Markdown Blog marketplace template](https://webstudio.is/marketplace/templates/markdown-blog).

-The screenshots use the Webstudio Updates project as a working example. Its
-filenames, fields, and category filter differ from the tutorial values below.
-
 <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

 Use the Content Engine for bounded, file-based content that should live with
-the site and remain portable as Markdown or JSON.
+the site and remain portable as Markdown, MDX, or JSON.

 Good fits include:

@@ -113,6 +110,7 @@ Write the article here.

 <figure><img src="../../.gitbook/assets/content-engine-markdown-editor.png" alt="Markdown editor showing article frontmatter and body"><figcaption><p>An article's metadata and body in the Markdown editor</p></figcaption></figure>

+
 ### Frontmatter

 The opening YAML block is called **frontmatter**. It must be the first block in
@@ -173,7 +171,7 @@ asset ID or generated filename. This is what makes the content portable.

 ### JSON files

-The Content Engine can query JSON files as well as Markdown. JSON files can
+The Content Engine can query JSON files as well as Markdown and MDX. JSON files can
 contain objects, arrays, or scalar values. A root object exposes its fields for
 structured queries:

@@ -221,6 +219,7 @@ page-level **Dynamic data**:

 <figure><img src="../../.gitbook/assets/content-engine-overview-query.png" alt="Assets overview query filtering Markdown files and drafts, then sorting by publication date and ID"><figcaption><p>An overview query for the Webstudio Updates project</p></figcaption></figure>

+
 Choosing only the fields the page renders keeps the published content data
 small. Leaving article bodies out of the overview also avoids loading every
 article just to display a list.
@@ -265,7 +264,8 @@ Add another Assets resource to the page-level **Dynamic data**:
   - `properties.slug` **equals** `system.params.slug`
   - `properties.draft` **does not equal** `true`

-<figure><img src="../../.gitbook/assets/content-engine-article-query.png" alt="Assets resource filtering one Markdown article by folder and the dynamic page slug"><figcaption><p>The article resource uses the dynamic slug from the page URL</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/content-engine-article-query.png" alt="Assets resource filtering one Markdown article by folder and the dynamic page slug"><figcaption><p>The article Resource uses the dynamic slug from the page URL</p></figcaption></figure>
+

 **Exactly one** returns the matching article directly at `post.data`. It also
 reports an error if two articles use the same slug. You do not need a
@@ -299,6 +299,30 @@ 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.
+
 ## 7. Publish the article

 Start new articles with `draft: true`. The overview and article queries above
@@ -320,21 +344,22 @@ will render it without another page design.

 ## Connect content with document references

-The Content Engine calls links between Markdown and JSON files **document
+The Content Engine calls links between Markdown, MDX, and JSON files **document
 references**. A document reference replaces an exact `$ref` object with data
 from another content file. This is Webstudio's syntax. It uses URI references
 for file paths and [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901)
 for values inside JSON files, but it does not implement JSON Schema resolution.

-Both supported source formats can reference either target format:
+All supported source formats can reference the other content formats:

-| Source | Where references can appear | JSON target | Markdown target |
+| Source | Where references can appear | JSON target | Markdown or MDX target |
 | --- | --- | --- | --- |
-| Markdown | YAML frontmatter | Yes | Yes |
+| Markdown or MDX | YAML frontmatter | Yes | Yes |
 | JSON | Anywhere in the document | Yes | Yes |

-References do not work inside a Markdown body. A `$ref` object can be nested in
-an object or array, including inside a file reached through another reference.
+References do not work inside a Markdown or MDX body. A `$ref` object can be
+nested in an object or array, including inside a file reached through another
+reference.

 ### Reference syntax

@@ -409,12 +434,12 @@ the resolved `properties.author` value is:
 }
 ```

-The same rules cover JSON to Markdown and Markdown frontmatter to JSON. A
-referenced file can contain its own references, so shared records can be
-composed across several files.
+The same rules cover JSON to Markdown or MDX and Markdown or MDX frontmatter to
+JSON. A referenced file can contain its own references, so shared records can
+be composed across several files.

 The Content Engine loads referenced data when a query filters, sorts, or
-returns a field that depends on it. The target must be another Markdown or JSON
+returns a field that depends on it. The target must be another Markdown, MDX, or JSON
 file in the project's compiled Assets. Missing files, invalid fragments, and
 reference cycles fail instead of returning partial data.

@@ -143,7 +143,10 @@ CSS variables, by nature, are available in the current instance and any of the c

 #### Global Variables

-<figure><img src="../../.gitbook/assets/global-root.png" alt="Global Root in Webstudio" width="375"><figcaption><p>Global Root</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/navigator-panel-dark.png">
+  <img src="../../.gitbook/assets/navigator-panel-light.png" alt="Navigator with Global root above Body and the page instance tree">
+</picture>

 Most variables should be defined on the Global Root, which is the highest level of the page and the same for every page. That way, you can define `--my-color`, and it's available on every instance on every page.

@@ -163,7 +166,7 @@ With CSS variables, you can interact with the parent and modify the styles of an

 Prefer CSS variables over a [descendant custom state](states-and-selectors.md#custom-states) such as `:hover .button` for parent-child interactions. They keep each property on the child that uses it and are especially useful when one parent state coordinates several properties or children. Define a variable on the parent, use it for the relevant property on each child, and change the variable's value in the parent's `:hover` state.

-<figure><img src="../../.gitbook/assets/parent-child-demo.gif" alt=""><figcaption><p>Hovering the link and the children change (icon color, icon bg, and arrow appears)</p></figcaption></figure>
+<figure><img src="../../.gitbook/assets/parent-child-demo.gif" alt="Hovering a link changes its child icon color, background, and arrow visibility"><figcaption><p>Hovering the link and the children change (icon color, icon bg, and arrow appears)</p></figcaption></figure>

 {% embed url="https://youtu.be/rg49mmDvdlE" %}
 Video tutorial
@@ -71,7 +71,29 @@ First, it's recommended to create [CSS variables](css-variables.md) to use withi

 You can style your site using Local or Tokens like this:

-<table data-header-hidden><thead><tr><th></th><th></th><th data-hidden></th></tr></thead><tbody><tr><td><img src="../../.gitbook/assets/style-sources.png" alt="Style sources" data-size="original"></td><td>The top of the Style Panel contains Style Sources. Here is where you can add new Tokens, select existing ones, and switch to Local styling.</td><td>The top section of the Style Panel is our <a href="https://www.reddit.com/r/diablo4/comments/148kfyt/psa_consolescontrollerbeginners_users/">Style Sources Input</a>. This is where you’ll create, style, and arrange your tokens.<br><br>When you select a component's instance on the canvas, the tokens you see inside this input are <em>sources</em> of the <em>styles</em> on that instance.</td></tr><tr><td><img src="../../.gitbook/assets/convert-to-token.png" alt="Convert local to token" data-size="original"></td><td>Want to style something immediately without making a Token? Use the Local Style Source. Styles applied on Local only impact that instance, but you can easily convert styles from Local to a new Token.</td><td>Want to style something immediately without making a token? Go for it. All component instances in Webstudio have this Local style source by default. Styles applied on Local are unique to an instance and can’t be re-used, but you can easily convert styles from Local to a new token through the token menu.</td></tr><tr><td><img src="../../.gitbook/assets/new-token.png" alt="Adding a new token" data-size="original"></td><td>To make a new Token, click inside the Style Sources input, type a name, and hit enter.</td><td>To make a new token, click inside the Style Sources Input, type a name, and hit ENTER/RETURN.</td></tr><tr><td><img src="../../.gitbook/assets/tokens-added.png" alt="Switching tokens" data-size="original"></td><td>The Token you’re currently styling will be blue in the Style Sources input, while others are gray. Simply click on another style source to select it. Any styling you do will be applied to the current Token and reflected across all instances of that Token.</td><td><p>The token you’re currently styling will be blue in the Style Sources Input, while others are gray. Simply click on another style source to select it.</p><p>Any styling you do will be applied to the current token and reflected across all instances of that token.</p><p>When you add a style, the label for that property will turn blue to show that it is applied on the current token.</p></td></tr><tr><td><img src="../../.gitbook/assets/property-label-tooltip.png" alt="" data-size="original"></td><td><p>Hover the label for a helpful description of where the styles on this property come from.</p><p>In this case, we see that the width value that we just applied is coming from the Base breakpoint, the “new token” token on the Body instance. See <a href="anatomy-of-the-webstudio-builder.md#label-colors">Label Colors</a> to understand what the different colors mean.</p></td><td><p>Hover the label for a helpful description of where the styles on this property come from.</p><p>In this case we see that the width value that we just applied is coming from the Base breakpoint, the “new token” token, on the Body instance.</p></td></tr><tr><td><img src="../../.gitbook/assets/empty-circle.png" alt="" data-size="original"></td><td>A circle in the Token indicates that there are no styles applied to the Token. This will go away as soon as you apply a style. For Local, a dot is added to the center of the circle when styles are added.</td><td></td></tr></tbody></table>
+1. Select an instance. The **Style sources** field at the top of the Style panel shows its Local styles and Tokens.
+
+   <img src="../../.gitbook/assets/style-sources.png" alt="Style sources field showing the Local source and applied Tokens" data-size="original">
+
+2. To create a Token, select the Style sources field, enter a name, and press Enter.
+
+   <img src="../../.gitbook/assets/new-token.png" alt="Style sources field with a new Token name ready to be added" data-size="original">
+
+3. Select the source you want to edit. The active source is highlighted, and new styles are written to that source.
+
+   <img src="../../.gitbook/assets/tokens-added.png" alt="Style sources field with several Tokens and one active Token" data-size="original">
+
+Use the Local source for styles that apply only to the selected instance. You can convert Local styles into a reusable Token later.
+
+<img src="../../.gitbook/assets/convert-to-token.png" alt="Local style source menu with the action to convert its styles to a Token" data-size="original">
+
+Hover a property label to see which breakpoint and style source provides its current value. See [Label colors](anatomy-of-the-webstudio-builder.md#label-colors) for the full reference.
+
+<img src="../../.gitbook/assets/property-label-tooltip.png" alt="Style property tooltip identifying the breakpoint, Token, and instance that provide the value" data-size="original">
+
+An empty circle means the source has no styles. A dot appears in the Local source after you add a style.
+
+<img src="../../.gitbook/assets/empty-circle.png" alt="Empty circle indicator beside a style source with no styles" data-size="original">

 ## Exporting human-readable classes

@@ -6,7 +6,7 @@ description: >-

 # ➕ Expression editor

-<figure><img src="../../.gitbook/assets/webstudio-expression-editor.png" alt=""><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/webstudio-expression-editor.png" alt="Binding popover with variables and an expression that reads a CMS title"><figcaption></figcaption></figure>

 Expression editor is available on every field when clicking the “+” button.

@@ -17,11 +17,14 @@ You can change modes in the Top Bar or via [keyboard shortcuts](shortcuts.md) if

 Additionally, you can open any project in [Safe Mode](modes.md#safe-mode), which disables script execution for security and troubleshooting purposes.

-<figure><img src="../../.gitbook/assets/builder-modes.png" alt=""><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/builder-modes-dark.png">
+  <img src="../../.gitbook/assets/builder-modes-light.png" alt="Mode menu with Design and Content options and their keyboard shortcuts">
+</picture>

 ## Design

-Designer mode provides the full power of the builder. For example, you can add and style components.
+Design mode provides the full power of the Builder. For example, you can add and style components.

 ## Content

@@ -93,7 +96,7 @@ Here’s what you need to know:

 - 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 your changes when you are ready for them to go live. To do so, open the publish dialog by clicking “Publish” in the top right, then click “Publish”. It takes around 45 seconds for the site to publish. Note, “Publish” may be disabled if the designer didn’t enable the publishing permission for you.
+- 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.

 ## Preview

@@ -6,7 +6,10 @@ description: Use the Navigator to view, select, and organize instances on your p

 The Navigator is a hierarchical panel on the left side of the builder that shows every instance on the current page as a tree. It reflects the exact nesting structure of your page and is the primary way to select, reorder, and organize instances — especially when they are stacked or overlapping on the canvas.

-<figure><img src="../../.gitbook/assets/navigator.png" alt="Navigator panel showing a tree of instances"><figcaption><p>The Navigator showing the page structure</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/navigator-panel-dark.png">
+  <img src="../../.gitbook/assets/navigator-panel-light.png" alt="Navigator panel showing Global root, Body, and a nested Content Block instance">
+</picture>

 ## Selecting instances

@@ -6,7 +6,10 @@ description: Configure per-page settings such as path, SEO, authentication, redi

 Page settings control how an individual page behaves — its URL, SEO metadata, authentication, status code, redirect, and more. Open Page Settings by clicking the gear icon next to any page in the Pages panel.

-<figure><img src="../../.gitbook/assets/page-settings-general.png" alt="Page settings panel showing Page name, Path, Status code, Redirect, and Language fields"><figcaption><p>General page settings</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/page-settings-dialog-dark.png">
+  <img src="../../.gitbook/assets/page-settings-dialog-light.png" alt="Page settings for the Home page with general and authentication fields above a search preview showing the Webstudio W favicon">
+</picture>

 ## Page name

@@ -140,7 +143,7 @@ Page authentication is useful for private previews, client-only pages, internal
 <figure><img src="../../.gitbook/assets/page-settings-authentication-enabled.png" alt="Page Settings Authentication section enabled with Login and Password fields"><figcaption><p>Page authentication</p></figcaption></figure>

 {% hint style="info" %}
-Authentication applies to protected pages on custom domains. Staging domains have their own built-in password protection, described in [Publishing & custom domains](publishing-and-custom-domains.md#staging-domain-password-protection).
+Authentication applies to protected pages on custom domains. Staging domains have their own built-in password protection, described in [Publishing & custom domains](publishing-and-custom-domains.md#staging-password-protection).
 {% endhint %}

 {% hint style="warning" %}
@@ -161,7 +164,10 @@ To protect multiple routes, dynamic paths, or wildcard sections of the site, use

 SEO settings that control how the page appears in search engine results.

-<figure><img src="../../.gitbook/assets/page-settings-seo.png" alt="SEO section showing Title, Description, Exclude from search, and search result preview"><figcaption><p>SEO settings with search result preview</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/page-settings-seo-dark.png">
+  <img src="../../.gitbook/assets/page-settings-seo-light.png" alt="Page settings Search section with the Webstudio W favicon in the result preview, the Blog title and description, search visibility, and en-US language fields">
+</picture>

 ### Title

@@ -179,13 +185,19 @@ Adds a `noindex` directive to the page, preventing search engines from indexing

 The Open Graph image displayed when the page is shared on social media (Facebook, X, LinkedIn, etc.). You can either upload an image or bind a URL expression to a dynamic image from your CMS.

-<figure><img src="../../.gitbook/assets/page-settings-social.png" alt="Social image section with social preview card"><figcaption><p>Social image with preview</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/page-settings-social-dark.png">
+  <img src="../../.gitbook/assets/page-settings-social-light.png" alt="Page settings Social image section with a selected blue and purple glass wave image and its social sharing preview">
+</picture>

 ## Custom metadata

 Add arbitrary `<meta>` tags to the page's `<head>`. Each entry has a **property** (the meta tag's `name` or `property` attribute) and a **content** value, both of which support expressions.

-<figure><img src="../../.gitbook/assets/page-settings-custom-metadata.png" alt="Custom metadata section with a property and content row filled in"><figcaption><p>Adding a custom meta tag</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/page-settings-custom-metadata-dark.png">
+  <img src="../../.gitbook/assets/page-settings-custom-metadata-light.png" alt="Page settings with a blue and purple wave image in the Social sharing preview above empty Custom metadata fields">
+</picture>

 Use this for meta tags not covered by the fields above, such as `og:type`, `twitter:card`, or any custom meta needed by third-party integrations.

@@ -6,7 +6,10 @@ description: Set project-wide configuration, including redirects, authentication

 Project settings are located in the top left by clicking the Webstudio logo > Project settings.

-<figure><img src="../../.gitbook/assets/project-settings.png" alt="Project settings located in top left" width="261"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/project-settings-menu-dark.png">
+  <img src="../../.gitbook/assets/project-settings-menu-light.png" alt="Builder menu with Project settings near the top">
+</picture>

 ## General

@@ -19,7 +22,10 @@ Project settings are located in the top left by clicking the Webstudio logo > Pr

 ### Atomic CSS

-<figure><img src="../../.gitbook/assets/atomic-css-setting.png" alt="Atomic css setting"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/atomic-css-setting-dark.png">
+  <img src="../../.gitbook/assets/atomic-css-setting-light.png" alt="Project settings Publishing section with Generate atomic CSS when publishing enabled">
+</picture>

 When enabled, the class and CSS structure under the hood contains one style per class. This algorithm allows classes to be reused, significantly reducing the amount of CSS, ultimately leading to a faster-loading website.

@@ -113,7 +119,10 @@ To add a protected route:

 Routes use the same syntax as page paths. See [Path syntax](page-settings.md#path-syntax) for supported static routes, dynamic segments, optional segments, and wildcards.

-<figure><img src="../../.gitbook/assets/project-settings-authentication.png" alt="Project Settings Authentication section with route, login, password fields, and protected route list"><figcaption><p>Project route authentication</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/project-settings-authentication-dark.png">
+  <img src="../../.gitbook/assets/project-settings-authentication-light.png" alt="Project settings Authentication section with route, login, password, and Add controls">
+</picture>

 Login and password rules:

@@ -126,7 +135,7 @@ Login and password rules:
 If a page has authentication in Page Settings and the same route is also protected in Project Settings, the page setting takes priority for that route.

 {% hint style="info" %}
-Authentication applies to protected routes on custom domains. Staging domains have their own built-in password protection, described in [Publishing & custom domains](publishing-and-custom-domains.md#staging-domain-password-protection).
+Authentication applies to protected routes on custom domains. Staging domains have their own built-in password protection, described in [Publishing & custom domains](publishing-and-custom-domains.md#staging-password-protection).
 {% endhint %}

 {% hint style="warning" %}
@@ -34,7 +34,8 @@ Enter the domain or subdomain you want the site to be available at, for example,

 After entering your domain, you will be provided with DNS records, which can be manually added to your DNS or automatically through Entri.

-<figure><img src="../../.gitbook/assets/add-new-domain.png" alt="CNAME and TXT records from new domain" width="362"><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/add-new-domain.png" alt="CNAME and TXT records for a new custom domain" width="362"><figcaption></figcaption></figure>
+

 ### 2. Add the DNS records

@@ -77,9 +78,7 @@ Verification may take up to 24 hours but usually takes only a few minutes.
 You must publish your site _after_ the domain is verified, or else "[Worker not found](publishing-and-custom-domains.md#domain-issues)" will show on the site.
 {% endhint %}

-{% hint style="info" %}
-Publishing currently takes around 45 seconds. During publishing, your Project is built into a JavaScript app and deployed to 300+ servers around the world.
-{% endhint %}
+Keep the Publish dialog open to follow the build and deployment status. Resolve any reported error before trying again.

 Once your site is live, you can visit it by clicking the open icon next to the green checkmark.

@@ -87,7 +86,11 @@ Once your site is live, you can visit it by clicking the open icon next to the g

 ## Publish to Staging

-<figure><img src="../../.gitbook/assets/staging-domain.png" alt="Publish to staging with production unchecked"><figcaption></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/staging-domain-dark.png">
+  <img src="../../.gitbook/assets/staging-domain-light.png" alt="Publish dialog with a verified staging domain and Add a new domain, Export, and Publish actions">
+</picture>
+

 You can publish your Project to a separate domain for testing before going live by only checking your staging domain, which can be the default Project subdomain or a custom domain.

@@ -237,7 +240,7 @@ DNS propagation typically takes 10-15 minutes, but can take up to 72 hours in ra

 #### Option 2: Publish your website on a `www` subdomain

-Go back to [Step 1](publishing-and-custom-domains.md#id-1.-add-a-new-domain-to-your-project), but this time, prefix your domain with `www`.
+Go back to [Step 1](publishing-and-custom-domains.md#1-add-a-new-domain-to-your-project), but this time, prefix your domain with `www`.

 #### Video Tutorial

@@ -263,7 +266,8 @@ To publish to a subdomain:

 You may see "Worker not Found" message when opening the site, like this:

-<figure><img src="../../.gitbook/assets/worker-not-found.png" alt="Worker not found"><figcaption></figcaption></figure>
+<figure><img src="../../.gitbook/assets/worker-not-found.png" alt="Published site showing a Worker not found error"><figcaption></figcaption></figure>
+

 Worker not found is due to one of the following reasons:

@@ -6,7 +6,10 @@ description: Use the Style Panel to apply CSS styles to any instance on your pag

 The Style Panel is on the right side of the builder. It exposes every CSS property visually and applies styles to the currently selected instance. All style changes are scoped by the active [breakpoint](breakpoints.md) and style source.

-<figure><img src="../../.gitbook/assets/style-panel.png" alt="Style Panel on the right side of the builder"><figcaption><p>The Style Panel</p></figcaption></figure>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/style-panel-dark.png">
+  <img src="../../.gitbook/assets/style-panel-light.png" alt="Style panel showing style sources, layout, grid child, spacing, and size controls">
+</picture>

 ## Style sources