Component maps

Different documentation frameworks name their components differently: what Docusaurus calls Admonition, Mintlify calls Note, and Nextra calls Callout. A component map tells Twain that a framework's component names correspond to its own built-in renderers, so a project's MDX renders as intended rather than as unknown-component placeholders.

Twain ships maps for four frameworks. The tables below name the built-in renderer each component maps onto. Components mapped to Tabs are drawn as stacked labelled panels with every panel visible at once, not as clickable tabs; Disclosure is a native collapsible <details> element.

Docusaurus

Component	Renders as
Tabs	Tabs
TabItem	Tab
Admonition	Callout
Details	Disclosure

The map covers the JSX form only. Docusaurus's directive syntax for admonitions, the :::note and ::: fenced form, is not supported by Twain and renders as ordinary paragraph text. Use <Admonition type="note">, or a GitHub-style alert, for a coloured box.

Mintlify

Component	Renders as
Note, Info, Tip, Check, Warning, Danger	Callout (coloured to match)
Card	Card
CardGroup, Columns	Card group
Steps, Step	Numbered steps
Tabs, Tab, CodeGroup	Tabs
Accordion, Expandable	Disclosure
AccordionGroup	Contents, with no wrapper
Frame	Figure

Nextra

Component	Renders as
Callout	Callout
Tabs, Tab, Tabs.Tab	Tabs
Steps	Numbered steps
Cards, Card, Cards.Card	Card group and cards

Fumadocs

Component	Renders as
Callout	Callout
Tabs, Tab	Tabs
Steps, Step	Numbered steps
Accordion	Disclosure
Accordions	Contents, with no wrapper
Cards, Card	Card group and cards

Choosing a map

In the app

The app reads a .twain-md.json file in the same folder as the document and honours its componentMap key. Set it to a framework name:

{ "componentMap": "docusaurus" }

The app reloads the document when this file changes, so you can adjust the map and see the result immediately. See Configuration file.

In the CLI and MCP server

The CLI accepts a --component-map option set to a framework name or to the path of a JSON file holding a map. Without the option it auto-detects a .twain-md.json, starting in the document's folder and walking up to the repository root or the working directory, whichever is higher; the first file found ends the search, even when it has no componentMap key.

The MCP server takes a componentMap tool argument, but only one of the four framework names. It does not read .twain-md.json, and it does not accept a custom map or a file path.

Custom maps

Instead of a framework name, componentMap can be an object mapping your own component names to built-in kinds:

{
  "componentMap": {
    "MyAdmonition": "callout",
    "MyTabSet": "tabs",
    "MyTab": "tab"
  }
}

The available kinds are callout (and coloured variants like callout:warning), tabs, tab, steps, step, card, cardgroup, details, summary, figure, figcaption, and fragment. For safety, Twain only accepts these fixed kinds; a map can never introduce new HTML tags, attributes, or URLs, so a project's configuration file cannot make a document less safe.

A map only applies to names Twain does not already render. The built-in callout names and the built-in components such as Card, Tabs, Steps and Details keep their own rendering, so an entry naming one of them has no effect. An entry whose kind is not in the list above is dropped, and that component falls back to a labelled placeholder.