@commercetools/nimbus-mcp 3.1.0 → 3.3.0

package/data/docs/routes/components-content-markdown.json

@@ -0,0 +1,548 @@
+{
+  "meta": {
+    "id": "Components-Markdown",
+    "title": "Markdown",
+    "exportName": "Markdown",
+    "description": "Renders a Markdown string into Nimbus-styled, accessible React elements with per-element overrides, custom renderers, and safe streaming for AI output.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/markdown/markdown.mdx",
+    "menu": [
+      "Components",
+      "Content",
+      "Markdown"
+    ],
+    "route": "components/content/markdown",
+    "tags": [
+      "component",
+      "markdown",
+      "content",
+      "streaming",
+      "ai",
+      "llm"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key features",
+        "href": "#key-features",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic usage",
+        "href": "#basic-usage",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Custom component tags",
+        "href": "#custom-component-tags",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Safe by default",
+        "href": "#safe-by-default",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Streaming",
+        "href": "#streaming",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nMarkdown turns a Markdown source string into Nimbus-styled, accessible React\nelements. It is built on the headless [`react-markdown`](https://github.com/remarkjs/react-markdown)\nengine (remark/rehype/unified), so all styling is owned by Nimbus — there is no\nforeign CSS. GitHub Flavored Markdown (tables, task lists, strikethrough,\nautolinks) is on by default.\n\nIts primary use case is rendering **agentic / LLM streaming output** in chat and\nassistant UIs; it also renders authored content like release notes and\ndescriptions.\n\n> [!NOTE]\\\n> Markdown is in **beta**. Code blocks render as semantic, token-styled\n> `pre`/`code` without syntax highlighting or a copy button in v1 — a richer\n> `CodeBlock` is a planned fast-follow.\n\n### Key features\n\n- **Default Nimbus renderers** for every standard element, composed from\n  existing design tokens (the Figma `Markdown/*` typography scale).\n- **Per-element overrides** — pass `components={{ a: MyLink }}` to replace any\n  element's renderer; all other defaults stay intact.\n- **Custom component tags** — register a non-standard key\n  (`components={{ SearchQueryResultCard: Card }}`) and embed that tag in the\n  source; its attributes arrive as props. Self-closing and paired-with-children\n  are both supported, any casing preserved.\n- **Safe by default** — raw HTML is never rendered, rendering is restricted to a\n  safe element allowlist, and dangerous URLs are neutralized.\n- **Streaming-aware** — `isStreaming` completes half-written tokens, memoizes\n  settled blocks, and manages an accessible busy/announcement model.\n\n## Basic usage\n\n```jsx live\nconst App = () => (\n  <Markdown>\n    {`# Hello\n\nThis is **Markdown** rendered with _Nimbus_ styling and a [link](https://commercetools.com).\n\n- Task lists\n- Tables\n- Code: \\`const x = 1\\``}\n  </Markdown>\n);\n```\n\n## Custom component tags\n\nTo render your own components inside Markdown, register them in `components`\nunder the tag name you want to use, then embed that tag in the source:\n\n```jsx live\nconst App = () => (\n  <Markdown\n    components={{\n      SearchQueryResultCard: ({ id }) => (\n        <Box border=\"solid-25\" borderColor=\"primary.6\" borderRadius=\"200\" p=\"400\">\n          <Text fontWeight=\"600\">Result for SKU {id}</Text>\n        </Box>\n      ),\n    }}\n  >\n    {`Here is what I found:\n\n<SearchQueryResultCard id=\"sku-42\" />`}\n  </Markdown>\n);\n```\n\nThe tag's string attributes are passed as props. Only registered tags are\nrendered — unregistered tags stay inert — so this stays safe by default.\n\n## Safe by default\n\nMarkdown has a single, safe security posture: raw HTML is never rendered, only a\nsafe element allowlist is rendered, and dangerous URLs (`javascript:`,\n`vbscript:`, `file:`) are neutralized. Image-host security is delegated to the\napplication's Content-Security-Policy, matching the Merchant Center convention.\nEmbed application components via custom component tags rather than raw HTML.\n\n## Streaming\n\nFor LLM output, set `isStreaming` while tokens arrive. Unterminated bold,\nitalic, inline code, and links are completed on the fly so the output never\nflashes literal `**` or `[` characters, and only the final block re-parses per\ntoken.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nMarkdown turns a Markdown source string into Nimbus-styled, accessible React\nelements. It is built on the headless [`react-markdown`](https://github.com/remarkjs/react-markdown)\nengine (remark/rehype/unified), so all styling is owned by Nimbus — there is no\nforeign CSS. GitHub Flavored Markdown (tables, task lists, strikethrough,\nautolinks) is on by default.\n\nIts primary use case is rendering **agentic / LLM streaming output** in chat and\nassistant UIs; it also renders authored content like release notes and\ndescriptions.\n\n> [!NOTE]\\\n> Markdown is in **beta**. Code blocks render as semantic, token-styled\n> `pre`/`code` without syntax highlighting or a copy button in v1 — a richer\n> `CodeBlock` is a planned fast-follow.\n\n### Key features\n\n- **Default Nimbus renderers** for every standard element, composed from\n  existing design tokens (the Figma `Markdown/*` typography scale).\n- **Per-element overrides** — pass `components={{ a: MyLink }}` to replace any\n  element's renderer; all other defaults stay intact.\n- **Custom component tags** — register a non-standard key\n  (`components={{ SearchQueryResultCard: Card }}`) and embed that tag in the\n  source; its attributes arrive as props. Self-closing and paired-with-children\n  are both supported, any casing preserved.\n- **Safe by default** — raw HTML is never rendered, rendering is restricted to a\n  safe element allowlist, and dangerous URLs are neutralized.\n- **Streaming-aware** — `isStreaming` completes half-written tokens, memoizes\n  settled blocks, and manages an accessible busy/announcement model.\n\n## Basic usage\n\n```jsx live\nconst App = () => (\n  <Markdown>\n    {`# Hello\n\nThis is **Markdown** rendered with _Nimbus_ styling and a [link](https://commercetools.com).\n\n- Task lists\n- Tables\n- Code: \\`const x = 1\\``}\n  </Markdown>\n);\n```\n\n## Custom component tags\n\nTo render your own components inside Markdown, register them in `components`\nunder the tag name you want to use, then embed that tag in the source:\n\n```jsx live\nconst App = () => (\n  <Markdown\n    components={{\n      SearchQueryResultCard: ({ id }) => (\n        <Box border=\"solid-25\" borderColor=\"primary.6\" borderRadius=\"200\" p=\"400\">\n          <Text fontWeight=\"600\">Result for SKU {id}</Text>\n        </Box>\n      ),\n    }}\n  >\n    {`Here is what I found:\n\n<SearchQueryResultCard id=\"sku-42\" />`}\n  </Markdown>\n);\n```\n\nThe tag's string attributes are passed as props. Only registered tags are\nrendered — unregistered tags stay inert — so this stays safe by default.\n\n## Safe by default\n\nMarkdown has a single, safe security posture: raw HTML is never rendered, only a\nsafe element allowlist is rendered, and dangerous URLs (`javascript:`,\n`vbscript:`, `file:`) are neutralized. Image-host security is delegated to the\napplication's Content-Security-Policy, matching the Merchant Center convention.\nEmbed application components via custom component tags rather than raw HTML.\n\n## Streaming\n\nFor LLM output, set `isStreaming` while tokens arrive. Unterminated bold,\nitalic, inline code, and links are completed on the fly so the output never\nflashes literal `**` or `[` characters, and only the final block re-parses per\ntoken.\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key features",
+          "href": "#key-features",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom component tags",
+          "href": "#custom-component-tags",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Safe by default",
+          "href": "#safe-by-default",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Streaming",
+          "href": "#streaming",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures rendered Markdown is usable by everyone, including people\nwho rely on assistive technology. The default renderers enforce WCAG 2.1 AA for\nthe content they produce; a consumer override or a custom component tag owns the\naccessibility of whatever it renders.\n\n```jsx live\nconst App = () => (\n  <Markdown>\n    {`Visit the [Nimbus docs](https://nimbus-documentation.vercel.app) — external links automatically get a visible icon, an \"(opens in new tab)\" label for assistive technology, and \\`rel=\"noopener noreferrer\"\\`.`}\n  </Markdown>\n);\n```\n\n### Headings (1.3.1, 2.4.6)\n\n- Headings render as semantic `<h1>`–`<h6>`. Use `headingOffset` to nest\n  rendered headings beneath the host page's outline.\n- The component never adds a heading-level skip, and it renders author skips\n  faithfully — a skip emits a development-mode warning rather than silently\n  rewriting structure.\n\n### Links (2.4.4, 1.4.1, 1.4.11)\n\n- External links get `rel=\"noopener noreferrer\"`, `target=\"_blank\"`, an i18n\n  \"(opens in new tab)\" label for assistive technology, and a visible icon\n  indicator that is conveyed by shape (not color alone) and meets ≥3:1 non-text\n  contrast.\n\n### Images (1.1.1)\n\n- Author `alt` text is preserved. A missing alt renders `alt=\"\"` (decorative)\n  and warns in development. Images carry `loading=\"lazy\"` and\n  `referrerpolicy=\"no-referrer\"`.\n\n### Tables (1.3.1)\n\n- Tables use real `<table>` / `<thead>` / `<th scope=\"col\">` semantics.\n\n### Lists & code\n\n- Real `<ul>` / `<ol>` and semantic `<pre><code>` are produced. GFM task-list\n  checkboxes are read-only with an accessible name derived from the item text.\n\n### Streaming (4.1.3)\n\n- While `isStreaming` is set, the root carries `aria-busy=\"true\"`. When the\n  stream settles, `aria-busy` clears and a single coalesced completion message\n  is announced via a polite live region — no per-token announcement spam, and no\n  ARIA wiring required from the consumer.\n\n### Color & motion\n\n- All default styles use AA-compliant tokens, and no streaming reveal animation\n  is introduced.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Headings (1.3.1, 2.4.6)",
+          "href": "#headings-131-246",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Links (2.4.4, 1.4.1, 1.4.11)",
+          "href": "#links-244-141-1411",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Images (1.1.1)",
+          "href": "#images-111",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tables (1.3.1)",
+          "href": "#tables-131",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Lists & code",
+          "href": "#lists--code",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Streaming (4.1.3)",
+          "href": "#streaming-413",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color & motion",
+          "href": "#color--motion",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n`Markdown` renders a Markdown source string into Nimbus-styled, accessible React\nelements. It is a single entry point (not a compound component) plus a default\nrenderer map, built on the headless `react-markdown` engine with `remark-gfm`\nenabled by default.\n\n### Import\n\n```tsx\nimport { Markdown, type MarkdownProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nPass the Markdown source as the single string child. GitHub Flavored Markdown —\ntables, task lists, strikethrough, autolinks — is on by default.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown maxW=\"60ch\">\n    {`# Release notes\n\nWe shipped **streaming** support and [GFM tables](https://github.github.com/gfm/).\n\n- A task list item\n- Inline code: \\`const x = 1\\`\n\n| Feature   | Status |\n| --------- | ------ |\n| Streaming | Beta   |\n`}\n  </Markdown>\n);\n```\n\n## Usage examples\n\n### Overriding an element renderer\n\nPass a `components` entry keyed by HTML element name to replace that one\nrenderer; every other default stays intact. Every renderer also receives the\noriginal hast `node` — destructure it out before spreading onto a DOM element.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown\n    components={{\n      a: ({ children, href }) => (\n        <Link href={href} fontColor=\"primary\">\n          {children}\n        </Link>\n      ),\n    }}\n  >\n    {`Route links through the app router, e.g. the [Nimbus docs](https://nimbus-documentation.vercel.app).`}\n  </Markdown>\n);\n```\n\n### Custom component tags\n\nRegister a non-standard key in `components` and you can embed that tag directly\nin the Markdown source. The tag's string attributes are passed to the component\nas props, and tag names match by exact case (PascalCase preserved). Both\nself-closing (`<Tag />`) and paired (`<Tag>…</Tag>`) forms are supported; keep\nblank lines around a block-level paired tag so its content parses as markdown.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown\n    components={{\n      SearchResultCard: ({ id }) => (\n        <Box border=\"solid-25\" borderColor=\"primary.6\" borderRadius=\"200\" p=\"400\">\n          <Text fontWeight=\"600\">Result for SKU {id}</Text>\n        </Box>\n      ),\n    }}\n  >\n    {`Here is what I found:\n\n<SearchResultCard id=\"sku-42\" />`}\n  </Markdown>\n);\n```\n\n### Preserving the page outline\n\nWhen embedding Markdown beneath host-page headings, set `headingOffset` so the\nrendered headings nest rather than compete. Markdown heading level `L` renders as\n`min(L + headingOffset, 6)`.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown headingOffset={1}>\n    {`# Looks like an h1 in source\n\nRenders as an h2, so it nests beneath a host page's h1.`}\n  </Markdown>\n);\n```\n\n### Constraining the measure with style props\n\nStyle props forward to the outer root container, so you can set `maxW`, color,\nspacing, `lineClamp`, etc.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown maxW=\"48ch\" color=\"neutral.11\">\n    {`Forwarding a \\`maxW\\` keeps long paragraphs at a comfortable line length. This paragraph wraps at roughly 48 characters so the measure stays readable instead of stretching the full container width.`}\n  </Markdown>\n);\n```\n\n### Restricting the element set\n\nPass `allowedElements` to render only an explicit set of elements (mutually\nexclusive with `disallowedElements`). Filtered elements are dropped while their\ntext content is preserved.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown allowedElements={[\"p\", \"strong\", \"em\"]}>\n    {`# This heading is filtered out\n\nOnly **paragraphs** and _inline emphasis_ survive the allowlist.`}\n  </Markdown>\n);\n```\n\n### Rendering streamed (LLM) output\n\nSet `isStreaming` while tokens arrive. Unterminated constructs are completed via\n`remend`, content is split into memoized blocks (only the final block re-parses\nper token), the root sets `aria-busy`, and a single coalesced completion\nannouncement is made when the stream settles. Consumers never manage ARIA.\n\n```jsx live-dev\nconst FULL = `# Streaming demo\n\nThis text is revealed **token by token**, and half-written constructs never flash raw markup.`;\n\nconst App = () => {\n  const [n, setN] = useState(0);\n  const streaming = n < FULL.length;\n\n  useEffect(() => {\n    if (!streaming) return;\n    const id = setTimeout(() => setN((v) => Math.min(v + 3, FULL.length)), 40);\n    return () => clearTimeout(id);\n  }, [n, streaming]);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Button size=\"xs\" alignSelf=\"start\" onPress={() => setN(0)}>\n        Replay\n      </Button>\n      <Markdown isStreaming={streaming}>{FULL.slice(0, n)}</Markdown>\n    </Stack>\n  );\n};\n```\n\n## Default renderers\n\nOut of the box every standard element maps to a Nimbus-styled renderer using the\nFigma `Markdown/*` typography scale. Headings `#`–`####` map to the heading\nscale; `#####`/`######` fold to the smallest. External links automatically get\n`target=\"_blank\"`, `rel=\"noopener noreferrer\"`, an \"(opens in new tab)\" label,\nand a visible icon indicator. Images render with `loading=\"lazy\"` and\n`referrerpolicy=\"no-referrer\"`.\n\n## Safe by default\n\nRaw HTML is never rendered as live markup: it is skipped, rendering is restricted\nto a safe element allowlist, and dangerous URLs (`javascript:`, `vbscript:`,\n`file:`) are neutralized. Image-host security is the application CSP's\nresponsibility (`img-src`). To render application components, register them as\ncustom component tags (above) rather than embedding raw HTML.\n\n```jsx live-dev\nconst App = () => (\n  <Markdown>\n    {`Raw HTML is skipped: <script>alert(1)</script> renders nothing.\n\nA [dangerous link](javascript:alert(1)) is neutralized.`}\n  </Markdown>\n);\n```\n\n## Accessibility\n\nThe default renderers enforce WCAG 2.1 AA and the component owns its own ARIA —\nincluding the streaming busy state and completion announcement, so no ARIA wiring\nis required from you. The two consumer-actionable items are:\n\n- **Preserve the outline** — set `headingOffset` when embedding beneath host\n  headings so rendered headings nest correctly.\n- **Author meaningful `alt`** — a missing image alt renders `alt=\"\"` and warns in\n  development.\n\nA consumer override or custom component tag owns the accessibility of whatever it\nrenders. See the **Accessibility** tab for the full per-element breakdown.\n\n## API reference\n\n<PropsTable id=\"Markdown\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Markdown in\nyour application. As the component's internal functionality is already tested by\nNimbus, these patterns help you verify your integration and application-specific\nlogic.\n\n### Basic rendering\n\nRender a Markdown string into Nimbus-styled, semantic elements\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Markdown, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MarkdownComponents } from \"./markdown.types\";\n\ndescribe(\"Markdown - Basic rendering\", () => {\n  it(\"renders headings, paragraphs, and inline formatting\", () => {\n    render(\n      <NimbusProvider>\n        <Markdown>{`# Release notes\\n\\nWe shipped **streaming** support.`}</Markdown>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"heading\", { level: 1, name: \"Release notes\" })\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"streaming\").tagName).toBe(\"STRONG\");\n  });\n});\n```\n\n### Overriding an element renderer\n\nReplace a single element's renderer; all other defaults stay intact\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Markdown, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MarkdownComponents } from \"./markdown.types\";\n\ndescribe(\"Markdown - Per-element override\", () => {\n  it(\"renders anchors with a custom component\", () => {\n    const components: MarkdownComponents = {\n      a: ({ children, href }) => (\n        <a data-tracking=\"external\" href={href}>\n          {children}\n        </a>\n      ),\n    };\n\n    render(\n      <NimbusProvider>\n        <Markdown components={components}>\n          {`Read the [docs](https://docs.example.com).`}\n        </Markdown>\n      </NimbusProvider>\n    );\n\n    const link = screen.getByRole(\"link\", { name: \"docs\" });\n    expect(link).toHaveAttribute(\"data-tracking\", \"external\");\n  });\n});\n```\n\n### Embedding custom component tags\n\nRegister a tag in `components`, then embed it in the source; its attributes arrive as props\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Markdown, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MarkdownComponents } from \"./markdown.types\";\n\ndescribe(\"Markdown - Custom component tags\", () => {\n  it(\"renders a registered custom tag with its attributes as props\", () => {\n    const components: MarkdownComponents = {\n      SearchQueryResultCard: (props: { id?: string; node?: unknown }) => (\n        <div data-testid=\"result-card\" data-id={props.id} />\n      ),\n    };\n\n    render(\n      <NimbusProvider>\n        <Markdown components={components}>\n          {`Top result:\\n\\n<SearchQueryResultCard id=\"sku-42\" />`}\n        </Markdown>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"result-card\")).toHaveAttribute(\n      \"data-id\",\n      \"sku-42\"\n    );\n  });\n\n  it(\"leaves an unregistered tag inert\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Markdown>{`Before <UnknownWidget /> after.`}</Markdown>\n      </NimbusProvider>\n    );\n\n    const root = container.querySelector(\".nimbus-markdown\");\n    expect(root?.querySelector(\"unknownwidget\")).toBeNull();\n    expect(screen.getByText(/Before/)).toBeInTheDocument();\n  });\n});\n```\n\n### Safe by default\n\nRaw HTML is never rendered as live markup, and dangerous URLs are neutralized\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Markdown, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MarkdownComponents } from \"./markdown.types\";\n\ndescribe(\"Markdown - Safe by default\", () => {\n  it(\"does not render raw HTML\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Markdown>{`Hello <script>alert(1)</script> world.`}</Markdown>\n      </NimbusProvider>\n    );\n\n    const root = container.querySelector(\".nimbus-markdown\");\n    expect(root?.querySelector(\"script\")).toBeNull();\n    expect(screen.getByText(/Hello/)).toBeInTheDocument();\n  });\n});\n```\n\n### Rendering streamed (LLM) output\n\nSet `isStreaming` so partial tokens render cleanly while a response streams in\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Markdown, NimbusProvider } from \"@commercetools/nimbus\";\nimport type { MarkdownComponents } from \"./markdown.types\";\n\ndescribe(\"Markdown - Streaming\", () => {\n  it(\"completes an unterminated construct so it renders as formatted content\", () => {\n    render(\n      <NimbusProvider>\n        {/* A model has emitted a half-written bold span. */}\n        <Markdown isStreaming>{`A sentence with **bold tex`}</Markdown>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"bold tex\").tagName).toBe(\"STRONG\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-content-markdown--docs)\n- [react-markdown](https://github.com/remarkjs/react-markdown)\n- [remark-gfm (GitHub Flavored Markdown)](https://github.com/remarkjs/remark-gfm)\n- [GitHub alerts syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Overriding an element renderer",
+          "href": "#overriding-an-element-renderer",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom component tags",
+          "href": "#custom-component-tags",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Preserving the page outline",
+          "href": "#preserving-the-page-outline",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Constraining the measure with style props",
+          "href": "#constraining-the-measure-with-style-props",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Restricting the element set",
+          "href": "#restricting-the-element-set",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Rendering streamed (LLM) output",
+          "href": "#rendering-streamed-llm-output",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default renderers",
+          "href": "#default-renderers",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Safe by default",
+          "href": "#safe-by-default",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Overriding an element renderer",
+          "href": "#overriding-an-element-renderer-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Embedding custom component tags",
+          "href": "#embedding-custom-component-tags",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Safe by default",
+          "href": "#safe-by-default-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Rendering streamed (LLM) output",
+          "href": "#rendering-streamed-llm-output-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nMarkdown guidelines ensure rendered rich text stays consistent, readable, and\naccessible across the product — whether the source is authored content or live\nAI output.\n\n### Best practices\n\n- **Register only trusted components:** custom component tags render only when\n  you register them in `components`, so register components you control and that\n  are safe to drive from the rendered source. Unregistered tags stay inert.\n- **Preserve the page outline:** when embedding Markdown inside a page that\n  already has headings, set `headingOffset` so the rendered headings nest\n  beneath the host heading rather than competing with it.\n- **Constrain measure for readability:** forward a `maxW` (e.g. `60ch`) so long\n  paragraphs wrap at a comfortable line length.\n- **Stream for AI:** set `isStreaming` while a model response is arriving so\n  partial tokens render cleanly and screen-reader users get a coherent\n  loading → done model.\n- **Provide alt text:** author images with meaningful `alt`. Decorative-only\n  images should still be intentional — a missing alt warns in development.\n\n### Usage\n\n- **Do** override individual element renderers when you need product-specific\n  behavior (e.g. routing links through your app router).\n- **Do** embed your own components with custom component tags (e.g. result\n  cards in chat output) instead of reaching for raw HTML.\n- **Do** keep code output simple in v1 — a plain styled code block is rendered;\n  rich code chrome is a fast-follow.\n- **Don't** rely on raw HTML in the source — it is never rendered as live markup.\n- **Don't** reimplement image-host allowlisting in the component — that is the\n  application Content-Security-Policy's job.\n\n### Content\n\n- Keep headings hierarchical; don't skip levels (a skip warns in development).\n- Use tables for tabular data only; GFM cannot express complex multi-header\n  tables.\n- Prefer descriptive link text over \"click here\".\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Content",
+          "href": "#content",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}