0 Fork 0

mirror of https://github.com/webstudio-is/webstudio.git synced 2026-10-23 03:27:27 +09:00

Files

T

Oleg Isonen 1b48716ff4 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-08-31 18:39:05 +02:00

4.3 KiB

Raw Blame History

description

description
The Element component is a flexible container for building layouts in Webstudio.

📦 Element

The Element component is a versatile component that can represent any HTML element. It provides the flexibility to create semantic HTML structures with any tag type while maintaining full styling capabilities.

How to Use the Element Component

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.

Components panel with Element listed first in the expanded General group

Available Tags

The Element component can be rendered as many HTML tags, including but not limited to:

Container Elements

div (default) – Generic container
section – Document section
article – Self-contained content
aside – Sidebar content
header – Header section
footer – Footer section
main – Main content
nav – Navigation section

Text Elements

span – Inline container
p – Paragraph (rendered as block)

List Elements

ul – Unordered list
ol – Ordered list
li – List item

Link Element

a – Anchor/link (shows href and target properties)

Table Elements

table – Table container
thead – Table header group
tbody – Table body group
tfoot – Table footer group
tr – Table row
th – Table header cell
td – Table data cell

Other Elements

address – Contact information
figure – Figure with optional caption
figcaption – Figure caption
label – Form label
dl – Description list
dt – Description term
dd – Description details

Changing the Tag

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

Settings panel for a paragraph element with Name, Show, Tag, ID, and Class controls

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.

Tag Labels in Navigator

When viewing Elements in the Navigator, the component label displays the HTML tag name (e.g., "section", "nav", "article"). This makes it easy to identify the semantic structure of your page at a glance.

{% hint style="info" %} You can rename Elements in the Navigator by double-clicking to give them more descriptive names like "Hero Section" or "Main Navigation" while still maintaining the correct HTML tag. {% endhint %}

Use Cases

Semantic HTML Structure

Use Element to create proper HTML5 semantic markup:

header for site headers
nav for navigation menus
main for primary content
article for blog posts
aside for sidebars
footer for footers

Custom Tables

Build accessible data tables using Element with table-related tags (table, thead, tbody, tr, th, td).

Description Lists

Create glossaries or key-value displays with dl, dt, and dd tags.

Links with Full Control

Use the a tag to create links with full styling control and access to the href and target properties.

Element vs Box

The Element component provides more flexibility than the Box component:

Feature	Element	Box
Tag options	Any HTML tag	div only
Semantic HTML	✅ Full support	❌ Limited
Navigator label	Shows HTML tag	Shows "Box"
Use case	Semantic structure	Quick containers

{% hint style="success" %} For building semantic, accessible websites, prefer Element over Box when you need specific HTML tags. {% endhint %}

Slot – Create reusable component slots
Link – Navigation and anchor elements
HTML Embed – Custom HTML code

4.3 KiB Raw Blame History Unescape Escape