Developers

Marking basics

Make any element editable with data-macro-key. Macro detects types, hydrates live values, and opens the overlay for editors.

One attribute is enough

Mark content with data-macro-key only. No per-page scripts and no CMS templates. Optional data-macro-type overrides auto-detection.

Supported types (overview)

Name	Type	Required	Description
`text`	`primitive`	optional	Plain text on headings, paragraphs, buttons, labels.
`image`	`primitive`	optional	Image asset; auto-detected on <img>.
`richtext`	`primitive`	optional	Formatted HTML — requires explicit data-macro-type.
`link`	`primitive`	optional	Anchor with href — auto on a[href].
`group`	`primitive`	optional	Ordered collection / repeater of child content keys.
`component`	`block`	optional	Custom or store block identified by typeId (e.g. @acme/hero).

Full tag inference and payload shapes: Primitive reference. Groups: Groups & repeaters. Components: Custom components.

Text

Default for headings, paragraphs, buttons, and other text nodes.

hero.html

<h1 data-macro-key="hero.title">Build faster</h1>
<p data-macro-key="hero.subtitle">Ship editable sites without a separate CMS front end.</p>

Image

<img> is auto-detected as image. You can still set data-macro-type="image" explicitly. Editors pick assets from the media library.

hero.html

<img
  data-macro-key="hero.image"
  data-macro-type="image"
  src="/hero.jpg"
  alt="Hero"
/>

Richtext

Use for formatted HTML blocks. Prefer a dedicated host element (often a <div>). Richtext is never inferred on bare div/section — set data-macro-type="richtext" (or macro/richtext).

article.html

<div
  data-macro-key="article.body"
  data-macro-type="richtext"
>
  <p>Default body copy shown until Macro hydrates the live value.</p>
</div>

Group (repeaters)

Groups hold ordered child keys — the foundation for lists and for items slots inside components. Editors add, remove, and reorder items in the overlay.

features.html

<section data-macro-key="home.features" data-macro-type="group">
  <!-- Items are managed by Macro; seed structure in the editor or via components/slots -->
</section>

Component

Multi-field blocks with a JSON payload and your own render(). Place a custom element (or any host) with the registered typeId.

home.html

<acme-hero
  data-macro-key="home.hero"
  data-macro-type="@acme/hero"
></acme-hero>

Key naming

Use stable, namespaced keys: home.hero.title, pricing.plans.
Keep keys unique per website — they are the content identity across locales.
Mirror page structure so editors recognize keys in the Dashboard explorer.

Don’t

Don’t encode locale in the key — locale lives in Macro’s i18n layer.
Don’t reuse the same key for unrelated content on different pages.
Don’t put secrets or one-off random IDs in keys unless you mean it.

Optional attributes

Name	Type	Required	Description
`data-macro-key`	`string`	required	Unique content key for this website (or key= on custom tags).
`data-macro-type`	`string`	optional	Primitive kind or component typeId. Optional when auto-detected.
`data-macro-sitewide`	`flag`	optional	Mark header/footer chrome shared across pages. See Sitewide chrome.
`data-macro-ssr`	`true`	optional	Set by prerender when content was injected at build time.

How editors experience it

After Quickstart and editor login, Macro highlights marked nodes. Text is inline-editable; images open the asset picker; components open the field sidebar. See the Editors handbook for draft, live, and publish.