# Markdoc and MDX

> How the body editor shows Markdoc tags and MDX components as blocks, what it keeps exactly as written, and what stops a save.

## The body editor

An entry's body opens in a writing view: paragraphs, headings, lists, quotes, code, links and images are edited as formatted text. "Edit as Markdoc" (or MDX, or Markdown) switches to the whole body as text, exactly as it's saved, and "Back to the writing view" returns.

A save rewrites only the blocks you changed. Untouched blocks keep their bytes, and so does the space between them. A changed block is written in one house style. Vesper reads the body with the same parser and options your site builds with, so the studio and the build see the same document.

## Markdoc tags as blocks

The studio reads the tags in `markdoc.config.mjs`, as `@astrojs/markdoc` does, and builds each tag's block from them. There's nothing to declare twice.

```js
// markdoc.config.mjs
import { component, defineMarkdocConfig } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    callout: {
      render: component('./src/components/Callout.astro'),
      children: ['paragraph', 'list'],
      attributes: {
        type: { type: String, default: 'note', matches: ['note', 'tip', 'warning'] },
        title: { type: String },
      },
    },
    youtube: {
      render: component('./src/components/YouTube.astro'),
      selfClosing: true,
      attributes: {
        id: { type: String, required: true },
        title: { type: String, required: true },
      },
    },
    abbr: {
      render: component('./src/components/Abbr.astro'),
      inline: true,
      attributes: { title: { type: String, required: true } },
    },
  },
});
```

How a tag sits in the body decides how it shows:

| In the body | In the writing view |
|---|---|
| An opening line, content, then a closing line | A frame. Its content stays editable, and only what the tag's `children` lists fits inside. |
| Self-closing, or with its content on the opening line | A card: one piece, with its settings |
| Inside a line of text (`inline: true`) | A chip in the text |

Each frame and card is named after its tag, with a Settings button. Its settings are the tag's attributes, with the same controls as frontmatter fields:

| Attribute | Control |
|---|---|
| `String` with a list of `matches` | Radio buttons for four values or fewer, otherwise a select |
| `String` with a pattern in `matches` | A text field checked against the pattern |
| `String`, or a custom type | A text field |
| `Number` | A number field |
| `Boolean` | A switch |
| `Array` or `Object`, with a `schema` hint | The controls that schema gives a field: a list of rows, a group |
| `Array`, `Object` or anything else | A raw YAML field |

Changes apply as you make them, so Ctrl+Z undoes them like typing. Changing a setting changes only that attribute's bytes in the tag. The rest of the tag, its content and its closing stay as written. A new tag is written with its attributes in schema order, leaving out empty values and defaults.

On the keyboard: arrow onto a block to select it, Enter opens its settings, Alt+↑ and Alt+↓ move it, and Delete removes it. Inside a frame, Escape selects the frame, and Escape again moves to the toolbar. Type "/" at the start of a line or after a space for a list of the blocks that fit where you are. The toolbar's Insert menu has the same list.

## Hints in vesper.config.ts

Names and help text for the studio live in `vesper.config.ts`, never in `markdoc.config.mjs`:

```ts
// vesper.config.ts
markdoc: {
  tags: {
    callout: {
      label: 'Callout',
      summary: 'type',
      attributes: {
        type: { labels: { note: 'Note', tip: 'Tip', warning: 'Warning' } },
        title: { description: 'Shown above the callout. Leave it empty to use the type.' },
      },
    },
    youtube: {
      label: 'YouTube video',
      summary: 'title',
      attributes: {
        id: { label: 'Video ID', description: 'The part after “v=” in the video’s address.' },
        title: { description: 'Describes the video for screen reader users.' },
      },
    },
  },
},
```

- `label` is the block's name. Without one, it's the tag's name in sentence case.
- `description` is help text for the tag.
- `summary` names the attribute whose value shows in the block's header, as in "Callout · Warning".
- Each attribute can have a `label`, a `description`, `labels` for its `matches` values, and a `widget` to choose its control by name. A widget applies as it would to a schema field of the attribute's type: a `String` attribute can take `textarea`, `url`, `color` or a custom widget. `Object` and `Array` attributes are edited as YAML, so a widget such as `geo` doesn't apply to them; naming one warns in the terminal and keeps the YAML field.
- An `Array` or `Object` attribute can also have a `schema`: a Zod schema for what's inside, written as for a content field, such as `z.array(z.object({ question: z.string(), answer: z.string() }))`. Markdoc can't describe what's inside a list, so this gives it real controls: each item a row, as lists of objects are in the form. Markdoc's own rules still decide what saves.
- A picture or another entry can go in a tag's settings too. In `vesper.config.ts` there's no `image` helper and no `reference()`, so use `fields.image()` with no helper and `fields.reference('collection')`. The studio offers the image picker, with uploads, and a list of the collection's entries. An image is stored as a path from your site's root, `/src/assets/barn.jpg`, and an entry as its ID:

```ts
// vesper.config.ts
markdoc: {
  tags: {
    gallery: {
      attributes: {
        items: {
          schema: z.array(
            z.object({ photo: fields.image(), sponsor: fields.reference('sponsors').optional() }),
          ),
        },
      },
    },
  },
},
```

  Astro doesn't resolve a path inside a tag's attributes, so the tag's component hands the image to `<Img>`, which does: `<Img image={item.photo} ratio="square" />`. Read an entry with `getEntry('sponsors', item.sponsor)`.
- A list attribute written one item per line, or one key per line, keeps that layout: changing one item rewrites only its lines, and new items follow the same layout. A list written on one line is written whole, as before. The same holds for an MDX component's array props.

## Links to other sites

Markdoc can't give one link its own settings, so whether a link opens in a new tab is a rule for the whole site. `links()` from `vespercms/markdoc` replaces Markdoc's link node: a link to another site opens in a new tab, and screen readers hear "(opens in a new tab)" after its words, which aren't shown. Links within the site stay in the tab, as do email and phone links.

```js
// markdoc.config.mjs
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import { links } from 'vespercms/markdoc';

export default defineMarkdocConfig({
  nodes: { link: links({ site: 'https://www.example.edu' }) },
});
```

- `site` is your site's address, so a full link to one of your own pages stays in the tab. Without it, every full web address counts as another site.
- `newTabLabel` changes the words screen readers hear, for a site in another language.

Editors write links as before, in the link dialog. The page changes only how they open.

## Partials and conditionals

Markdoc's `partial` tag is a card with a file picker. It lists `.mdoc` files whose names start with `_` or that sit in a `partials` folder, nearest the entry first, and stores the path relative to the entry, as Astro resolves it.

A conditional is a frame named "Conditional content". Its content is editable, and its settings hold the condition as Markdoc writes it, such as `$product.beta` or `equals($tier, "free")`. An `else` inside it shows as "Otherwise":

```md {% process=false %}
{% if $product.beta %}
This feature is in beta, and may change.
{% else /%}
This feature is ready to use.
{% /if %}
```

The "/" list doesn't offer conditionals. Write a new one in the source view.

## Tables

A pipe table is a grid in the writing view, in Markdown, Markdoc and MDX alike. Arrow onto it and press Enter to move into its cells, onto the one you last used.

- The arrow keys move between cells. Home and End go to the ends of the row, and Ctrl+Home and Ctrl+End to the first and last cells.
- Enter or F2 edits a cell in place, with bold, italic, code and links on their usual shortcuts. Enter or Escape keeps the change, and Tab and Shift+Tab go on to the next or previous cell. Tab in the last cell adds a row.
- Table actions, the "…" above the table or Shift+F10 on a cell, insert, move and delete rows and columns, and align a column left, centre or right. Alt and the arrow keys move a row or a column too. The header row stays first.
- Ctrl+Z undoes one change at a time, and Escape returns to the text with the table selected.

A save changes only what you changed: one cell's text, one row's line, or one cell in each line for a column. Rows without outer pipes keep that shape. In a table padded so its pipes line up, a changed cell is padded to its column when it fits, so no other row changes. A `|` typed in a cell is saved as `\|`. A new table from "/" or the Insert menu is written compactly, as `| a | b |` over `|---|---|`.

Some tables stay kept as written, edited as text:

- Markdoc's own `{% table %}` tag;
- a cell with HTML (such as `<br>` for a line break), a character reference such as `&nbsp;`, a footnote, a reference-style link, a link with a title, or a Markdoc annotation;
- a row with more or fewer cells than the header;
- a table inside a list or a quote, which is kept with it.

## Kept as written

Some things aren't safe to retype in a writing view, so the studio protects them. It never reformats them.

- **Variables, functions and annotations** are chips in the text. Their settings are a small text field, edited as written.
- **Everything else the writing view can't show faithfully** is a block named in words, such as "HTML, kept as written": tags `markdoc.config.mjs` doesn't define, HTML, comments, the tables above, footnotes and reference-style links. You edit it as raw text, in its own dialog or in the source view.

## What stops a save

The studio checks the body as you type. A problem stops the save only when your site's build would fail on it:

- a required attribute that's missing
- a value the attribute's type or `matches` doesn't allow
- an attribute the tag doesn't have
- a partial whose file doesn't exist
- MDX props that fail their schema

Each message names the block, as in "YouTube video: Title is required."

Other problems are warnings. Markdoc's own warnings stay warnings, such as content a tag's `children` doesn't list. Undefined variables aren't reported at all, because pages can pass variables in.

Tags and functions the site doesn't define depend on the mode. In local mode, the dev server checks every save again with your real `markdoc.config.mjs`. Unknown tags and functions then stop the save, and custom attribute types and `validate` functions run too. On the deployed site, in GitHub mode and the cloud, the studio checks with what it knows of your config, so unknown tags only warn, and your site's build is the last check for custom validators.

Tags and declared components also get accessibility notes from their own schema. A required `title`, `alt`, `label` or `aria-label` left empty is a note, and a tag with a `captions` attribute asks you to confirm captions when it's absent or off. See [Accessibility](/docs/site/accessibility/).

## MDX components

MDX components don't declare their props anywhere the studio can read. So a component is a block only when you declare it in `vesper.config.ts`, with a Zod props schema from `astro/zod`:

```ts
// vesper.config.ts
import { defineConfig } from 'vespercms/config';
import { fields } from 'vespercms/fields';
import { z } from 'astro/zod';

export default defineConfig({
  mdx: {
    components: {
      Callout: {
        label: 'Callout',
        summary: 'type',
        children: true,
        props: z.object({
          type: fields.select({ note: 'Note', tip: 'Tip', warning: 'Warning' }).default('note'),
          title: z.string().optional(),
        }),
      },
      YouTube: {
        label: 'YouTube video',
        props: z.object({ id: z.string(), title: z.string() }),
      },
    },
  },
});
```

```md
<Callout type="tip" title="Before you apply">
Check the deadline for your program.
</Callout>

<YouTube id="abc123" title="A walk across campus" />
```

- `children: true` makes the component a frame whose content stays editable. Without it, the component is a card.
- `inline: true` puts it inside a line of text instead.
- `label`, `description` and `summary` work as they do for Markdoc tags. Props get the same controls as frontmatter fields, so `fields.*` helpers and `.meta()` hints work there too.
- The studio checks props with your own schema, in every mode. The schema loads the first time an MDX body needs it.
- A prop that holds code, such as a function, or a spread of props, is shown read only and kept byte for byte. A component with a spread isn't checked.
- Undeclared components, expressions, imports and exports are kept as written.
