X Markdown

🎯 Skill Positioning

This skill focuses on one job: render Markdown correctly and predictably with @antdv-next/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
• 🚀 Quick Start Decision Guide
• 🛠 Recommended Workflow
• 🚨 Development Rules
• 🤝 Skill Collaboration
• 🔗 Reference Resources

📦 Package Boundaries

⚠️ x-markdown is not a chat-state tool. Use it to render content after @antdv-next/x and @antdv-next/x-sdk have already produced the message data.

🚀 Quick Start Decision Guide

🛠 Recommended Workflow

1. Start with CORE.md and get a plain render working first. 2. Add STREAMING.md only when the content arrives chunk-by-chunk. 3. Add EXTENSIONS.md when you need custom tags, plugins, syntax blocks, or themes. 4. Use API.md to confirm prop names and defaults instead of guessing.

Minimal Setup Reminder

import { XMarkdown } from "@antdv-next/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

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 Vue.
• Use `x-markdown` when the content itself needs Markdown parsing, streaming recovery, or rich component rendering.

🔗 Reference Resources

• CORE.md - Package boundaries, install/setup, safe defaults, common render patterns
• STREAMING.md - Chunked rendering, incomplete syntax recovery, loading vs done behavior
• EXTENSIONS.md - Components, plugins, themes, custom tag guidance
• API.md - Generated API reference from the official x-markdown docs

Official Docs

• XMarkdown Introduction
• XMarkdown Examples
• XMarkdown Streaming
• XMarkdown Components
• XMarkdown Plugins
• XMarkdown Themes

StreamingOption

TailConfig

AnimationConfig

Related Docs

• Component Extension
• Streaming

Core Guide

Package Boundaries

Install and Minimal Render

npm install @antdv-next/x-markdown

import { XMarkdown } from "@antdv-next/x-markdown";

const content = `
# Hello

- item 1
- item 2
`;

export default () => <XMarkdown content={content} />;

Safe Defaults

• Use content or children, not both.
• Start with plain Markdown before adding plugins or custom components.
• Use openLinksInNewTab when model output may contain external links.
• Use escapeRawHtml when raw HTML should remain visible but should not execute.
• If real HTML rendering is required, explicitly review dompurifyConfig.

Common Integration Patterns

Basic content block

<XMarkdown content={message} className="x-markdown-light" />

Chat message rendering

Render plain text or Markdown from message data after useXChat has already produced the message list.

<XMarkdown content={message.message.content} openLinksInNewTab escapeRawHtml />

Minimal checklist

• Confirm the content is actually Markdown, not a structured component schema.
• Keep rendering concerns out of Provider classes.
• Keep transport concerns out of XMarkdown.
• Add themes and custom components only after basic rendering works.

When to Read Other References

• Read STREAMING.md when content arrives incrementally from an LLM.
• Read EXTENSIONS.md when you need custom tags, code blocks, plugins, or themes.
• Read API.md for the full prop tables.

Extensions Guide

Components

components is the main extension point. Use it to map Markdown or custom HTML tags to Vue components.

import { Mermaid, Sources, Think } from "@antdv-next/x";
import { XMarkdown } from "@antdv-next/x-markdown";

<XMarkdown
  content={content}
  components={{
    mermaid: Mermaid,
    think: Think,
    sources: Sources,
  }}
/>;

Rules for component mappings

• Keep the mapping object stable across renders.
• Use streamStatus to separate temporary loading UI from final rendering.
• If a custom component contains block children, consider paragraphTag to avoid invalid nested markup.
• Keep custom tags semantically clear and avoid ambiguous mixed Markdown/HTML blocks.

Plugins

Built-in plugins are imported from @antdv-next/x-markdown/plugins/... and wired through config.

import Latex from "@antdv-next/x-markdown/plugins/Latex";

<XMarkdown
  content={content}
  config={{
    extensions: Latex(),
  }}
/>;

Use a plugin when the syntax extension belongs in parsing, not when it is only a visual replacement of a rendered node.

Themes

Start from a built-in theme stylesheet.

import "@antdv-next/x-markdown/themes/light.css";

<XMarkdown className="x-markdown-light" content={content} />;

For customization:

1. Keep the built-in theme class. 2. Add one custom class. 3. Override only the CSS variables you actually need.

Custom Tag Guidance

• Keep custom tag blocks well formed.
• Avoid stray blank lines inside custom HTML blocks unless the syntax is intentional.
• If newlines inside custom tags matter, review protectCustomTagNewlines.

Pick the Right Tool

• Use components for replacing rendered nodes with Vue components.
• Use plugins for parsing new syntax.
• Use themes for typography, spacing, and color.
• Use dompurifyConfig and escapeRawHtml for safety, not for visual customization.

Streaming Guide

When to Use

Use streaming mode when the Markdown content is appended chunk-by-chunk and may temporarily contain incomplete syntax.

Typical examples:

• partial links like [docs](https://example
• partial tables
• unfinished code fences
• a tail cursor while the assistant is still generating

Core Rule

hasNextChunk must reflect reality:

• true while more chunks are expected
• false for the final chunk so cached incomplete fragments flush into the final render

Minimal Streaming Setup

<XMarkdown
  content={content}
  streaming={{
    hasNextChunk,
    enableAnimation: true,
    tail: true,
  }}
/>

Incomplete Syntax Handling

Use incompleteMarkdownComponentMap when unfinished fragments should show custom loading UI instead of broken Markdown.

<XMarkdown
  content={content}
  streaming={{
    hasNextChunk,
    incompleteMarkdownComponentMap: {
      link: "link-loading",
      table: "table-loading",
    },
  }}
  components={{
    "link-loading": LinkSkeleton,
    "table-loading": TableSkeleton,
  }}
/>

Loading vs Done

Custom components receive streamStatus:

• loading: syntax may still be incomplete
• done: final content is available

Use this to delay expensive parsing or API calls until the syntax is complete.

Chat-Oriented Guidance

• Use a tail indicator only while the assistant is still generating.
• Keep placeholder components lightweight.
• If a component depends on a closed block or fenced payload, wait for streamStatus === 'done'.
• Do not keep hasNextChunk stuck at true, or the final Markdown will never settle.

Debugging Checklist

• Final chunk still looks incomplete: confirm hasNextChunk becomes false.
• Placeholder never disappears: confirm the mapped tag name exists in components.
• Performance looks unstable: disable animation and placeholder components first, then add them back selectively.