Choose MDX components

Use built-in components directly in an MDX page without importing them. Choose a component by the content it needs to present, then copy its source example.

The linked Mintlify syntax references provide longer examples. Margin’s supported behavior is described here; a tag being supported does not mean every Mintlify prop or layout behavior is supported.

Choose callouts and layoutsCopy Anchor Link

Use a callout for information that changes how the reader completes a task. Use cards for destinations and columns for side-by-side content.

CardGroup and Columns use the same grid. cols accepts 1 through 4 and defaults to 2. Panel currently renders its children inline; it does not replace the table-of-contents column. For the image examples, add your own image at images/preview.png relative to the docs root.

Organize procedures and alternativesCopy Anchor Link

Use Steps when the reader must perform actions in sequence. Use Tabs for alternative instructions and CodeGroup when the alternatives are code samples. Keep optional detail in an accordion rather than hiding a required action.

CodeGroup takes fenced code blocks. Give every fence a title so the tab label identifies the sample:

<CodeGroup>

```json title="docs.json"
{"name": "Acme"}
```

```md title="index.mdx"
# Welcome
```

</CodeGroup>

Read the code-group syntax reference for larger examples.

View creates selectable content variations from consecutive sibling tags. Write the variations next to each other without an authored ViewGroup wrapper:

<View title="Hosted">Connect the repository on Manicule.</View>
<View title="Self-hosted">Deploy the Margin application.</View>

See the view syntax reference. Unlike numbered steps, views represent alternatives rather than actions to complete in order.

Describe API contractsCopy Anchor Link

Use ParamField for an input and ResponseField for an output. These components describe fields; they do not send requests or enforce validation.

The names and data below illustrate a hypothetical API, not a Margin endpoint. RequestExample and ResponseExample currently render inline as code groups, not in a separate right-hand example column:

<RequestExample>

```json title="Request body"
{"name": "Example"}
```

</RequestExample>

<ResponseExample>

```json title="Response body"
{"id": "example"}
```

</ResponseExample>

The example syntax reference has larger request and response samples. Use Expandable inside a field description when the field contains child attributes.

Add diagrams and annotationsCopy Anchor Link

Use diagrams for relationships and trees for file structure. Keep status labels and definitions near the content they qualify.

GitHub is used through GitHub.Repo. The card fetches repository details in the visitor’s browser and falls back to a repository link when details are unavailable. Prompt displays its description and copy control; the prompt body is not displayed as page prose.

The supported built-in member tags are Tree.File, Tree.Folder, FileTree.File, FileTree.Folder, Color.Item, Color.Row, and GitHub.Repo. Other dotted names are not accepted as built-in members.

Target readers and reuse contentCopy Anchor Link

Use audience wrappers when human instructions and agent instructions need to differ. Content outside an audience wrapper remains available to both readers.

Visibility recognizes for="agents" and for="humans". Agent content is absent from the human HTML rendition; human content is omitted from agent Markdown. An omitted or unrecognized for value addresses both audiences. Audience wrappers select presentation, not access permissions.

Before using the snippet example, create snippets/shared-note.mdx under the docs root with the content to reuse. Margin expands the snippet into the page during ingest.

Handle unknown componentsCopy Anchor Link

An unknown capitalized component is removed as a wrapper during ingest. Its children remain, and the build records a component_unknown warning rather than failing for that unknown name. The component’s layout and behavior do not survive.

For example, an unsupported wrapper around a sentence leaves the sentence as ordinary content:

<CustomBox>Check the build diagnostics.</CustomBox>

The result is Check the build diagnostics. without a box. An unknown self-closing component has no children to preserve. Replace unknown tags with the closest built-in component, and check the rendered page as well as the build diagnostics. Misspelled or unsupported member tags follow the same warning-and-unwrapping behavior.