Visual editing for static sites

A free-form markdown page is hard to render as a visual editor — the structure changes per page and the editor has no idea what fields to surface. Block-based content fixes that: every page's frontmatter includes a content_blocks array, each entry tagged with a discriminator (_type: or _component:) that names which block shape it follows.

Once that structure exists, the editor can:

• look up the block's schema by discriminator
• render the right inputs for the right fields
• validate on save against the same shape the build reads
• show array-item previews using the block's preview: slot
• dispatch the cog-button to the right schema file when the block is referenced via $ref

The file on disk stays plain markdown with a YAML frontmatter array. Your static-site build does not need any awareness of the CMS.

Typed inputs at every level. A field is text, paragraph, richtext, number, boolean, date, color, range, link, image, file, select, multichoice, group, or array. Each type renders the right widget, validates with the right rules, and stores the right shape on disk.

Per-block previews. Every block declares a preview: slot with title:, description:, image: resolvers. Array items in the editor render as proper rows ("Hero — E-shopy postavené tak, aby prodávaly") instead of opaque "Item #3" placeholders. Without previews, multi-shape arrays are unusable; with them, authors can tell their content apart at a glance.

$ref shared blocks with strict enforcement. When button appears in five blocks, you define it once in blocks/button.yml and reference it via $ref: button from each parent. The validator rejects schemas that inline the same shape in two blocks, so shared shapes can never silently diverge. The editor's cog button opens the source-of-truth file directly — edits propagate.

Block-based content adds a small amount of structure to your markdown frontmatter — for the page editor to be useful, your content_blocks need to be tagged with a discriminator. If your existing pages are free-form markdown, the AI scaffolder can mostly migrate them, but some manual reshaping is realistic.

In exchange:

• Visual editing for non-technical authors without an SDK, framework integration, or rebuild-the-frontend project.
• A schema you can evolve — add a field, the editor surfaces it; deprecate one, the orphan panel shows it until you decide.
• No vendor lock-in — the structure is YAML in your repo, no proprietary export format.

The trade is worth it for marketing sites, documentation, and any page that has a finite vocabulary of layout components. It is probably not the right model for free-form long-form publishing where every post is fundamentally different in shape — there a richer markdown / MDX editor wins.