camox-block

name

camox-block

description

How to create Camox block definition files. Use this skill whenever the user wants to create a new block for their Camox website, add a page section/component, build a reusable content block, or asks about the block definition API. Trigger on mentions of blocks, sections, page components, content types, or any request to add new visual sections to a Camox site — even if they don't say 'block' explicitly.

Creating Camox Block Definitions

A block is a reusable page section (hero, testimonial, gallery, footer...). Users compose pages by assembling blocks. This skill covers creating block definitions — the template that describes a block's schema and rendering. Not the content (an instance of a block).

After defining the block: load camox-cli

A definition only adds a new type of block to the catalog — it doesn't put one on any page. Users almost never just want "a definition"; they want a section that actually shows up on the site. Once the block is defined and the dev server has picked it up, load the camox-cli skill to create an instance on the relevant page (or to wire it into a layout's before/after slot via camox-layout if it's chrome). If the user asks for "a hero on the homepage", the work is: define the block here, then create a hero block on the home page via the CLI. Don't stop after the definition — that leaves a dangling block type the user has to place by hand.

Quick Start

A block file lives in the app's src/blocks/ folder, is a .tsx file, and exports block:

import { Type, createBlock } from "camox/createBlock";

const myBlock = createBlock({
  id: "my-block", // Must match filename (kebab-case)
  title: "My Block", // Human-readable name
  description: "...", // Tells the AI when/how to use this block
  content: {
    /* ... */
  }, // Editable content schema
  settings: {
    /* ... */
  }, // Optional config toggles
  component: MyBlockComponent,
  toMarkdown: (c) => [`# ${c.title}`, c.description], // Markdown template
});

function MyBlockComponent() {
  return (
    <section>
      <myBlock.Field name="title">{(props) => <h1 {...props} />}</myBlock.Field>
    </section>
  );
}

export { myBlock as block };

The createBlock options

Option	Required	Description
id	yes	Unique kebab-case identifier. Must match the filename without extension.
title	yes	Display name shown in the CMS UI.
description	yes	Tells the AI assistant when to use this block and what content it expects. Write it like guidance for an LLM — be specific about placement, tone, and content guidelines.
content	yes	An object where each key is a field name and each value is a Type.* call. These fields are inline-editable in the CMS.
settings	no	Same shape as content, but for configuration that lives in a settings panel (not inline). Only Type.Enum and Type.Boolean should be used here.
layoutOnly	no	If true, the block won't appear in the "add block" sheet — it can only be placed inside layouts (e.g. navbar, footer).
component	yes	A named React function component that renders the block.
toMarkdown	yes	A builder function (c, s) => (...)[] that renders block content as markdown. c is a proxy typed on your content keys; s is a proxy typed on your settings keys used to wrap lines in conditionals. Each returned entry becomes a paragraph (joined with \n\n). Lines where all referenced fields resolve to empty — or whose condition is false — are omitted.

Markdown Template (toMarkdown)

toMarkdown is a builder function that controls how block content is rendered as markdown for AI features (summaries, SEO). It receives:

• c — a proxy typed on your content keys (c.title, c.description…)
• s — a proxy typed on your settings keys, used to wrap lines in conditionals

…and returns an array of entries. Each entry becomes a paragraph (joined with \n\n).

A bare c.fieldName is the default for single-field lines. Use template literals when combining fields or adding markdown syntax:

toMarkdown: (c) => [`# ${c.title}`, c.description, c.cta];

Field resolution rules:

• String: raw text value
• Link: [text](href)
• Image: ![alt](filename)
• File: [filename](url)
• Embed: raw URL string
• Repeater: each item rendered via its own toMarkdown (if set on the Repeater options), items joined with \n\n
• ImageList / FileList: each asset rendered as a markdown bullet
• Boolean/Enum: raw string value

Lines where ALL referenced fields resolve to empty are omitted from output.

Examples:

// Hero block
createBlock({
  toMarkdown: (c) => [`# ${c.title}`, c.description, c.illustration, c.cta],
  content: { ... },
})

// Testimonial — combine fields on one line
createBlock({
  toMarkdown: (c) => [`> ${c.quote}`, `— ${c.author}, ${c.title}, ${c.company}`],
  content: { ... },
})

// Statistics — Repeater with its own toMarkdown
createBlock({
  toMarkdown: (c) => [`## ${c.subtitle}`, c.description, c.statistics],
  content: {
    subtitle: Type.String({ default: "..." }),
    description: Type.String({ default: "..." }),
    statistics: Type.Repeater({
      content: {
        number: Type.String({ default: "100M+" }),
        label: Type.String({ default: "pages served" }),
      },
      minItems: 4,
      maxItems: 8,
      toMarkdown: (c) => [`**${c.number}** — ${c.label}`],
    }),
  },
})

The builder is type-safe — accessing a key that doesn't exist on content (e.g. c.titl) is a TypeScript error.

Conditional lines from settings

The second s argument is a proxy over your settings keys. Wrap a line (or array of lines) to make it conditional on a setting:

// Boolean setting — include a line only when the setting is true
toMarkdown: (c, s) => [`# ${c.title}`, c.description, s.showCta(c.cta)];

// Boolean wrapping multiple lines — all included together, or all dropped
toMarkdown: (c, s) => [
  `# ${c.title}`,
  s.showDetails([c.subtitle, c.description, c.backgroundImage]),
  c.cta,
];

// Enum — emit different lines depending on the selected variant
toMarkdown: (c, s) => [
  `# ${c.title}`,
  s.variant("banner", `**${c.headline}** — ${c.subtext}`),
  s.variant("inline", `${c.headline}: ${c.cta}`),
];

Only Type.Boolean and Type.Enum settings can be used this way — trying to reference any other setting is a type error. On a Repeater's own toMarkdown, s refers to the item's own settings (not the parent block's).

Content Field Types

Import Type from "camox/createBlock". Every field requires a default value.

Type.String

Inline-editable text. The workhorse field type. String fields support inline markdown-style formatting in rendered site output: **bold**, *italic*, ***bold italic***, and text links like [label](https://example.com) or internal page links inserted by the editor.

Type.String({
  default: "Hello world", // Required
  title: "Heading", // Optional label
  maxLength: 280, // Optional
  minLength: 1, // Optional
  pattern: "^[A-Z]", // Optional regex
});

Type.Boolean

A toggle. Use in settings for config, or in content for user-controlled flags.

Type.Boolean({ default: false, title: "Show background" });

Type.Enum

A dropdown with predefined options. Most commonly used in settings.

Type.Enum({
  default: "left",
  options: { left: "Left", center: "Center", right: "Right" },
  title: "Alignment",
});

The default must be one of the keys in options.

Type.Link

A link with text, URL (or internal page reference), and new-tab toggle.

Type.Link({
  default: { text: "Learn more", href: "/", newTab: false },
  title: "CTA",
});

Type.Image

A single image — render with block.Image.

Type.Image({ title: "Cover photo" });

Type.ImageList

A flat array of images — render with block.ImageList (NOT block.Repeater).

Type.ImageList({ defaultItems: 6, title: "Gallery images" });

Type.File

A single file upload, with MIME type filtering — render with block.File.

Type.File({
  accept: ["application/pdf"],
  title: "PDF Document",
});

Type.FileList

A flat array of files — render with block.FileList (NOT block.Repeater).

Type.FileList({
  accept: ["application/pdf"],
  defaultItems: 0,
  title: "Documents",
});

Type.Embed

A URL validated against a regex pattern. Used for embedding external content.

Type.Embed({
  pattern: "https:\\/\\/(www\\.)?(youtube\\.com|youtu\\.be)\\/.+",
  default: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  title: "YouTube URL",
});

The default must match the pattern — an error is thrown at definition time otherwise.

Type.Repeater

An array of structured items. Each item is an object with its own fields. This is how you create lists of things (testimonials, features, stats, links...).

Type.Repeater({
  content: {
    name: Type.String({ default: "Feature" }),
    description: Type.String({ default: "Description" }),
  },
  minItems: 1, // Must be >= 1
  maxItems: 10,
  title: "Features",
  toMarkdown: (c) => [`### ${c.name}`, c.description], // Required markdown template for each item
});

The toMarkdown option on Repeater defines how each item is rendered as markdown when the parent block's toMarkdown references this field. It is required, same as on the block itself.

Repeaters can be nested — an item can contain another Repeater:

columns: Type.Repeater({
  content: {
    title: Type.String({ default: "Column" }),
    links: Type.Repeater({
      content: {
        link: Type.Link({ default: { text: "Link", href: "#", newTab: false } }),
      },
      minItems: 1,
      maxItems: 999,
      toMarkdown: (c) => [c.link],
    }),
  },
  minItems: 2,
  maxItems: 4,
  title: "Columns",
  toMarkdown: (c) => [`### ${c.title}`, c.links],
});

Rendering in the Component

The component is a regular React function. It uses methods on the block constant to render each field. Every field renderer uses a render-prop pattern where the child function receives (props, data):

• props — spread onto the rendered element. Contains HTML/React attributes: refs, data attributes, event handlers, and field-specific attributes like to, src, alt, children. Use props in the vast majority of cases.
• data (second argument) — raw field values for advanced use cases where props doesn't suffice (e.g. conditional styling based on a link's href, using an image URL as a CSS background). Not meant to be spread — treat it as an escape hatch.

Rendering String fields — block.Field

<myBlock.Field name="title">{(props) => <h1 {...props} />}</myBlock.Field>

The name must match a key in content that is a Type.String. Spread props onto the element — props.children contains the rendered content. This is what makes the field inline-editable in the CMS.

In site output, props.children renders supported inline formatting (**bold**, *italic*, text links). By default, text links render as underlined <a> elements. Customize inline rendering with the optional components prop:

<myBlock.Field
  name="description"
  components={{
    link: (props, data) => (
      <a
        {...props}
        className={data.external ? "text-blue-600 underline" : "text-primary font-medium"}
      />
    ),
    strong: (props) => <strong {...props} className="font-semibold" />,
    emphasis: (props) => <em {...props} className="italic text-muted-foreground" />,
  }}
>
  {(props) => <p {...props} />}
</myBlock.Field>

The components.link callback receives (props, data). Spread props onto your link element; data exposes { target, href, external, pageId } for styling external vs. internal links. components.strong customizes **bold**; components.emphasis customizes *italic*. The same components prop is available on item.Field inside repeaters.

When the content needs to be placed inside a more complex structure, use props.children explicitly:

<myBlock.Field name="quote">
  {(props) => <blockquote {...props}>"{props.children}"</blockquote>}
</myBlock.Field>

Rendering Link fields — block.Link

Inside the render prop, use the Link component from camox/navigation instead of a plain <a> tag. This enables client-side navigation for internal links. The framework computes to, target, and rel from the link value — just spread props.

import { Link } from "camox/navigation";

<myBlock.Link name="cta">{(props) => <Link {...props} />}</myBlock.Link>;

The optional second argument data exposes raw values { text, href, newTab } for custom logic:

<myBlock.Link name="cta">
  {(props, { href }) => <Link {...props} className={href === "/" ? "active" : ""} />}
</myBlock.Link>

Rendering Image fields — block.Image

<myBlock.Image name="cover">{(props) => <img {...props} />}</myBlock.Image>

props includes src and alt. The optional data argument exposes the raw ImageValue for cases like background images:

<myBlock.Image name="cover">
  {(_props, { url }) => <div style={{ backgroundImage: `url(${url})` }} />}
</myBlock.Image>

Rendering File fields — block.File

<myBlock.File name="document">{(props) => <a {...props}>Download</a>}</myBlock.File>

props includes href and download (filename). The optional data argument exposes the raw FileValue.

Rendering Embed fields — block.Embed

<myBlock.Embed name="videoUrl">{(props) => <iframe {...props} />}</myBlock.Embed>

props includes src. The optional data argument exposes { url } for cases where the URL needs transformation:

<myBlock.Embed name="videoUrl">
  {(_props, { url }) => <iframe src={transformUrl(url)} />}
</myBlock.Embed>

Rendering Repeater fields — block.Repeater

<myBlock.Repeater name="features">
  {(item) => (
    <div>
      <item.Field name="name">{(props) => <h3 {...props} />}</item.Field>
      <item.Field name="description">{(props) => <p {...props} />}</item.Field>
    </div>
  )}
</myBlock.Repeater>

Inside a Repeater, the item callback argument exposes the same .Field, .Link, .Image, .File, .Embed, .ImageList, .FileList, and .Repeater methods — scoped to that item. This is how nested repeaters work too:

<footer.Repeater name="columns">
  {(column) => (
    <column.Repeater name="links">
      {(linkItem) => <linkItem.Link name="link">{(props) => <Link {...props} />}</linkItem.Link>}
    </column.Repeater>
  )}
</footer.Repeater>

Image and File lists — block.ImageList / block.FileList

For Type.ImageList use block.ImageList; for Type.FileList use block.FileList (NOT block.Repeater). The render-prop is the same shape as block.Image / block.File — (props, data) => … — invoked once per asset:

// Top-level
<gallery.ImageList name="images">
  {(props) => <img {...props} className="rounded-lg" />}
</gallery.ImageList>

// Nested inside a Type.Repeater
<paragraphGrid.Repeater name="paragraphs">
  {(item) => (
    <item.ImageList name="logos">
      {(props) => <img {...props} className="size-10 object-contain" />}
    </item.ImageList>
  )}
</paragraphGrid.Repeater>

Repeater is only for Type.Repeater arrays. Trying to use Repeater on an ImageList / FileList is a TypeScript error.

Reading settings — block.useSetting

function MyComponent() {
  const theme = myBlock.useSetting("theme");
  const compact = myBlock.useSetting("compact");
  // Use these values in your JSX for conditional rendering/styling
}

Detached rendering — block.Detached

Renders content outside the block's DOM container. Useful for fixed/floating elements like sticky navbars or modals. Uses a render prop that provides props with ref, onClick, onMouseEnter, and onMouseLeave — spread these onto the root element.

<myBlock.Detached>
  {(props) => (
    <div {...props} className="fixed top-0 left-0 right-0 z-50">
      {/* floating content */}
    </div>
  )}
</myBlock.Detached>

Rules and Conventions

1. File = one block. One .tsx file per block in src/blocks/. The id must match the filename (without .tsx).
2. Named export as block. Always: export { myVar as block }. Not a default export.
3. Named function component. Use function MyComponent(), not an arrow function. Reference it in createBlock before its declaration is fine (hoisting).
4. All fields need defaults. Every Type.* call requires a default value (images and files get automatic placeholders).
5. Description is for the AI. Write the description as guidance for an LLM — explain when to use this block, what kind of content it's for, and where it fits on a page.
6. toMarkdown is required. Every block must define how its content renders as markdown. Use the builder function (c) => [...] and reference content fields via c.fieldName.
7. Settings = Enum and Boolean only. Keep settings simple. Use content for everything the user edits inline.
8. Repeater minItems >= 1. You can't have an empty repeater — there's always at least one item.
9. Import path is "camox/createBlock". Both Type and createBlock come from this import.
10. Use Tailwind CSS for styling. All example blocks use Tailwind utility classes. Follow the same patterns: container mx-auto px-4 for centered content, responsive breakpoints, etc.