x-markdown

# 🎯 Skill Positioning **This skill focuses on one job**: render Markdown correctly and predictably with `@ant-design/x-markdown`. It covers: - Basic rendering and package boundaries - LLM streaming output and incomplete syntax handling - Custom component mapping for rich chat or data-display blocks - Plugins, themes, and safe rendering defaults ## Table of Contents - [📦 Package Boundaries](#-package-boundaries) - [🚀 Quick Start Decision Guide](#-quick-start-decision-guide) - [🛠 Recommended Workflow](#-recommended-workflow) - [🚨 Development Rules](#-development-rules) - [🤝 Skill Collaboration](#-skill-collaboration) - [🔗 Reference Resources](#-reference-resources) # 📦 Package Boundaries | Layer | Package | Responsibility | | --- | --- | --- | | **UI layer** | `@ant-design/x` | Chat UI, bubble lists, sender, rich interaction components | | **Data layer** | `@ant-design/x-sdk` | Providers, requests, streaming data flow, state management | | **Render layer** | `@ant-design/x-markdown` | Markdown parsing, streaming rendering, plugins, themes, custom renderers | > ⚠️ `x-markdown` is not a chat-state tool. Use it to render content after `@ant-design/x` and `@ant-design/x-sdk` have already produced the message data. # 🚀 Quick Start Decision Guide | If you need to... | Read first | Typical outcome | | --- | --- | --- | | Render Markdown with the smallest setup | [CORE.md](reference/CORE.md) | `XMarkdown` renders trusted content with basic styling | | Render LLM streaming chunks | [STREAMING.md](reference/STREAMING.md) | Correct `hasNextChunk`, placeholders, tail indicator, loading states | | Replace tags with business components | [EXTENSIONS.md](reference/EXTENSIONS.md) | Stable `components` map for custom tags and code blocks | | Add plugins or theme overrides | [EXTENSIONS.md](reference/EXTENSIONS.md) | Plugin imports, theme class wiring, minimal CSS overrides | | Check prop details and defaults | [API.md](reference/API.md) | Full prop table for `XMarkdown` and streaming options | # 🛠 Recommended Workflow 1. Start with [CORE.md](reference/CORE.md) and get a plain render working first. 2. Add [STREAMING.md](reference/STREAMING.md) only when the content arrives chunk-by-chunk. 3. Add [EXTENSIONS.md](reference/EXTENSIONS.md) when you need custom tags, plugins, syntax blocks, or themes. 4. Use [API.md](reference/API.md) to confirm prop names and defaults instead of guessing. ## Minimal Setup Reminder ```tsx import { XMarkdown } from '@ant-design/x-markdown'; export default () => <XMarkdown content="# Hello" />; ``` # 🚨 Development Rules - Prefer a stable `components` object. Do not create new inline component mappings on every render. - Use `streaming.hasNextChunk = false` on the final chunk, otherwise incomplete placeholders will not flush into final content. - Treat raw HTML carefully. Prefer `escapeRawHtml` when raw HTML should stay visible as text. - If raw HTML must be rendered, keep `dompurifyConfig` explicit and minimal. - Keep theme overrides small. Start from `x-markdown-light` or `x-markdown-dark` and override only the variables you need. - If a custom component depends on complete syntax, branch on `streamStatus === 'done'`. # 🤝 Skill Collaboration | Scenario | Recommended skill combination | Why | | --- | --- | --- | | Rich assistant replies in chat | `x-chat-provider` → `x-request` → `use-x-chat` → `x-markdown` | Provider and request handle data flow, `x-markdown` handles final rendering | | Built-in provider with Markdown replies | `x-request` → `use-x-chat` → `x-markdown` | Keep request config and rendering concerns separate | | Standalone Markdown page or docs viewer | `x-markdown` only | No chat data flow needed | ## Boundary Rules - Use **`x-chat-provider`** when adapting an API shape. - Use **`x-request`** when configuring transport, auth, retries, or streaming separators. - Use **`use-x-chat`** when managing chat state in React. - Use **`x-markdown`** when the content itself needs Markdown parsing, streaming recovery, or rich component rendering. # 🔗 Reference Resources - [CORE.md](reference/CORE.md) - Package boundaries, install/setup, safe defaults, common render patterns - [STREAMING.md](reference/STREAMING.md) - Chunked rendering, incomplete syntax recovery, loading vs done behavior - [EXTENSIONS.md](reference/EXTENSIONS.md) - Components, plugins, themes, custom tag guidance - [API.md](reference/API.md) - Generated API reference from the official `x-markdown` docs ## Official Docs - [XMarkdown Introduction](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/introduce.en-US.md) - [XMarkdown Examples](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/examples.en-US.md) - [XMarkdown Streaming](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/streaming.en-US.md) - [XMarkdown Components](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/components.en-US.md) - [XMarkdown Plugins](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/plugins.en-US.md) - [XMarkdown Themes](https://github.com/ant-design/x/blob/main/packages/x/docs/x-markdown/themes.en-US.md)