@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/Markdown/Markdown.doc.mjs

@@ -5,8 +5,7 @@ const anatomy = [
   {
     name: 'Document',
     required: true,
-    description:
-      'Root container for block or inline Markdown content.',
+    description: 'Root container for block or inline Markdown content.',
   },
   {
     name: 'Heading',
@@ -41,7 +40,8 @@ const anatomy = [
   {
     name: 'Table',
     required: false,
-    description: 'Scrollable table block rendered from Markdown rows and columns.',
+    description:
+      'Scrollable table block rendered from Markdown rows and columns.',
   },
   {
     name: 'Divider',
@@ -138,14 +138,20 @@ export const docs = {
       name: 'contentAlign',
       type: "'start' | 'center'",
       description:
-        "Alignment of prose content within the container when contentWidth is narrower than the available space.",
+        'Alignment of prose content within the container when contentWidth is narrower than the available space.',
       default: "'start'",
     },
+    {
+      name: 'plugins',
+      type: 'readonly MarkdownPluginEntry[]',
+      description:
+        'Ordered extensions created by createMarkdownPlugin(). Plugins may add bounded syntax, immutable typed AST transforms, and typed extension renderers. Use isMarkdownExtensionNode() to narrow extension data observed from other plugins. Renderer callbacks are pure; return a child component when hooks are needed. Omitted and empty lists preserve the released Markdown behavior.',
+    },
     {
       name: 'inlinePlugins',
       type: 'MarkdownInlinePlugin[]',
       description:
-        'Transforms regex matches in parsed text nodes into custom inline React elements. Use for issue refs, diff refs, mentions, and other shorthand patterns. Inline code and fenced code blocks are unaffected.',
+        'Transforms regex matches in parsed text nodes into custom inline React elements. Use for prefixed identifiers, mentions, and other shorthand patterns. Inline code, fenced code blocks, and math are unaffected.',
     },
     {
       name: 'autolink',
@@ -156,7 +162,8 @@ export const docs = {
     {
       name: 'components',
       type: 'MarkdownComponents',
-      description: 'Custom React component overrides for rendered Markdown elements (code, inlineCode, link, heading, paragraph, image, blockquote, hr, citation).',
+      description:
+        'Custom React component overrides for rendered Markdown elements (code, inlineCode, math, link, heading, paragraph, image, blockquote, hr, citation). Providing math enables `$…$` inline and `$$…$$` display parsing and receives `{value, display}`; omit it when dollar text should stay literal.',
     },
     {
       name: 'xstyle',
@@ -184,7 +191,8 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      children: '## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from \'@astryxdesign/core/Button\';\n```\n\n**Bold**, *italic*, and `inline code` all work.',
+      children:
+        "## Getting Started\n\nInstall the package:\n\n```bash\nnpm install @astryxdesign/core\n```\n\nThen import and use any component:\n\n```tsx\nimport {Button} from '@astryxdesign/core/Button';\n```\n\n**Bold**, *italic*, and `inline code` all work.",
     },
   },
   theming: {
@@ -229,11 +237,76 @@ export const docs = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse an existing synchronous transform-only Remark plugin; it stays out of every other bundle. Prove each plugin with fixtures: anything outside the supported MDAST subset — async work, parser or compiler plugins, processor state, raw HTML, unsupported nodes, forged positions, or metadata Astryx cannot represent — keeps the last valid document and reports one diagnostic.",
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',
+      },
+      {
+        guidance: true,
+        description:
+          'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
   examples: [
@@ -259,23 +332,191 @@ import {Text} from '@astryxdesign/core/Text';
 `,
     },
     {
-      label: 'Inline Plugins',
+      label: 'Text transform helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownPlugin,
+  createMarkdownTextTransform,
+} from '@astryxdesign/core/Markdown/plugins';
+
+const finalLabels = createMarkdownPlugin({
+  name: 'final-labels',
+  apiVersion: 1,
+  transform: createMarkdownTextTransform({
+    pattern: /\\bDraft\\b/g,
+    requiredSubstrings: ['Draft'],
+    replace: () => ({type: 'text', value: 'Final'}),
+  }),
+});
+
+<Markdown plugins={[finalLabels]}># Draft</Markdown>;
+`,
+    },
+    {
+      label: 'Semantic fence helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownFenceTransform,
+  createMarkdownPlugin,
+  type MarkdownExtensionNode,
+} from '@astryxdesign/core/Markdown/plugins';
+
+type DiagramNode = MarkdownExtensionNode<
+  'diagrams',
+  'diagram',
+  {readonly code: string; readonly label?: string},
+  'block'
+>;
+
+const diagrams = createMarkdownPlugin<'diagrams', DiagramNode>({
+  name: 'diagrams',
+  apiVersion: 1,
+  transform: createMarkdownFenceTransform({
+    languages: ['mermaid'],
+    createNode: ({code, meta}) => ({
+      type: 'extension',
+      plugin: 'diagrams',
+      name: 'diagram',
+      display: 'block',
+      data: {code, ...(meta == null ? {} : {label: meta})},
+    }),
+  }),
+  renderers: {
+    diagram: {
+      render: ({node}) => (
+        <Diagram source={node.data.code} label={node.data.label} />
+      ),
+      toText: node => node.data.code,
+    },
+  },
+});
+
+<Markdown plugins={[diagrams]}>
+  {'\`\`\`mermaid Checkout flow\\ngraph LR; A-->B\\n\`\`\`'}
+</Markdown>;
+`,
+    },
+    {
+      label: 'Source decoration helper',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {
+  createMarkdownPlugin,
+  createMarkdownSourceDecoration,
+  getMarkdownSourceDecorations,
+} from '@astryxdesign/core/Markdown/plugins';
+
+// Ranges are UTF-16 offsets into the same string Markdown renders. Every
+// block a range touches is annotated; rendering, copyable text, and ids
+// never change.
+const searchHits = createMarkdownPlugin({
+  name: 'search-hits',
+  apiVersion: 1,
+  transform: createMarkdownSourceDecoration({
+    name: 'search-hit',
+    ranges: [{start: 0, end: 15, data: {query: 'release'}}],
+  }),
+});
+
+const readDecorations = createMarkdownPlugin({
+  name: 'read-decorations',
+  apiVersion: 1,
+  transform: root => {
+    report(root.children.map(getMarkdownSourceDecorations));
+    return root;
+  },
+});
+
+<Markdown plugins={[searchHits, readDecorations]}>{source}</Markdown>;
+`,
+    },
+    {
+      label: 'Native frontmatter',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {createMarkdownFrontmatter} from '@astryxdesign/core/Markdown/plugins';
+
+const frontmatter = createMarkdownFrontmatter({
+  name: 'document-metadata',
+  parse: fields => ({
+    title: fields.title ?? 'Untitled',
+    draft: fields.draft === 'true',
+  }),
+});
+
+const source = '---\\ntitle: Release notes\\ndraft: true\\n---\\n# Shipped';
+const result = frontmatter.parse(source);
+
+<Markdown plugins={[frontmatter.plugin]}>{source}</Markdown>;
+`,
+    },
+    {
+      label: 'Compatible Remark plugin',
+      code: `
+import {Markdown} from '@astryxdesign/core/Markdown';
+import {createMarkdownPlugin} from '@astryxdesign/core/Markdown/plugins';
+import {createMarkdownRemarkTransform} from '@astryxdesign/core/Markdown/remark';
+
+// A synchronous transform-only Remark plugin in the usual attacher shape.
+const remarkRename =
+  ({from, to}) =>
+  tree => {
+    const rename = node => {
+      if (node.type === 'text') {
+        node.value = node.value.split(from).join(to);
+      }
+      node.children?.forEach(rename);
+    };
+    rename(tree);
+  };
+
+const productName = createMarkdownPlugin({
+  name: 'product-name',
+  apiVersion: 1,
+  transform: createMarkdownRemarkTransform(remarkRename, {
+    from: 'Astryx',
+    to: 'Astryx Design',
+  }),
+});
+
+<Markdown plugins={[productName]}># Astryx release notes</Markdown>;
+`,
+    },
+    {
+      label: 'Entity links',
       code: `
 import {Link} from '@astryxdesign/core/Link';
 
-const issuePlugins = [
+const entityPlugins = [
   {
     pattern: /\\b([A-Z][A-Z0-9]+-\\d+)\\b/g,
     render: (match, key) => (
-      <Link key={key} href={\`/issues/\${match[1]}\`}>
+      <Link key={key} href={\`/entities/\${match[1]}\`}>
         {match[0]}
       </Link>
     ),
   },
 ];
 
-<Markdown inlinePlugins={issuePlugins}>
-  {'Fixed PROJ-123. Inline code stays plain: \`PROJ-999\`.'}
+<Markdown inlinePlugins={entityPlugins}>
+  {'See DOC-2048. Inline code stays plain: \`DOC-9999\`.'}
+</Markdown>;
+`,
+    },
+    {
+      label: 'Math renderer',
+      code: `
+import {BlockMath, InlineMath} from 'react-katex';
+
+function MathExpression({value, display}) {
+  const Component = display === 'block' ? BlockMath : InlineMath;
+  return <Component math={value} />;
+}
+
+<Markdown components={{math: MathExpression}}>
+  {'Inline $x_1 + y$ and display math:\\n\\n$$\\n\\\\sum_i x_i\\n$$'}
 </Markdown>;
 `,
     },
@@ -315,8 +556,7 @@ export const docsZh = {
     {
       name: 'isStreaming',
       type: 'boolean',
-      description:
-        '启用流式模式，使用增量解析和淡入动画处理分块文本。',
+      description: '启用流式模式，使用增量解析和淡入动画处理分块文本。',
       default: 'false',
     },
     {
@@ -348,14 +588,20 @@ export const docsZh = {
       name: 'contentAlign',
       type: "'start' | 'center'",
       description:
-        "当 contentWidth 小于可用空间时，正文内容在容器内的对齐方式。",
+        '当 contentWidth 小于可用空间时，正文内容在容器内的对齐方式。',
       default: "'start'",
     },
+    {
+      name: 'plugins',
+      type: 'readonly MarkdownPluginEntry[]',
+      description:
+        '由 createMarkdownPlugin() 创建的有序扩展。插件可添加有界语法、不可变的类型化 AST 转换和类型化扩展渲染器。使用 isMarkdownExtensionNode() 缩小从其他插件观察到的扩展数据类型。渲染回调必须是纯函数；需要 Hook 时请返回子组件。省略或传入空列表时保持已发布的 Markdown 行为。',
+    },
     {
       name: 'inlinePlugins',
       type: 'MarkdownInlinePlugin[]',
       description:
-        '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于 issue 引用、diff 引用、用户提及等简写模式。内联代码和围栏代码块不受影响。',
+        '将已解析文本节点中的正则匹配转换为自定义内联 React 元素。适用于带前缀的标识符、用户提及等简写模式。内联代码、围栏代码块和数学表达式不受影响。',
     },
     {
       name: 'autolink',
@@ -363,6 +609,12 @@ export const docsZh = {
       description:
         "可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则：裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除；代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",
     },
+    {
+      name: 'components',
+      type: 'MarkdownComponents',
+      description:
+        '用于覆盖 Markdown 渲染元素的自定义 React 组件（code、inlineCode、math、link、heading、paragraph、image、blockquote、hr、citation）。提供 math 会启用 `$…$` 行内数学和 `$$…$$` 块级数学解析，并接收 `{value, display}`；不提供时美元符号保持原样。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -372,12 +624,14 @@ export const docsZh = {
     {
       name: 'className',
       type: 'string',
-      description: '根元素的 CSS 类名。建议使用 xstyle，className 适用于非 StyleX 系统集成。',
+      description:
+        '根元素的 CSS 类名。建议使用 xstyle，className 适用于非 StyleX 系统集成。',
     },
     {
       name: 'style',
       type: 'CSSProperties',
-      description: '根元素的内联样式。建议使用 xstyle，内联样式会绕过 StyleX 优化。',
+      description:
+        '根元素的内联样式。建议使用 xstyle，内联样式会绕过 StyleX 优化。',
     },
     {
       name: 'data-testid',
@@ -443,11 +697,76 @@ export const docsZh = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns like issue refs, diff refs, and mentions instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse an existing synchronous transform-only Remark plugin; it stays out of every other bundle. Prove each plugin with fixtures: anything outside the supported MDAST subset — async work, parser or compiler plugins, processor state, raw HTML, unsupported nodes, forged positions, or metadata Astryx cannot represent — keeps the last valid document and reports one diagnostic.",
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math. The renderer owns typesetting and accessible output; Astryx passes the expression as text and never executes raw HTML.',
+      },
+      {
+        guidance: true,
+        description:
+          'For direct parsing, use MathParseOptions and handle InlineNodeWithMath or BlockNodeWithMath. Incremental math parsing also uses createIncrementalState<true>() and IncrementalParseState<true>; default calls and ParseOptions annotations keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pair with Outline and useOutlineFromMarkdown for section navigation: headings render generated id attributes that match the outline item ids, so hash links scroll to their target.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
 };
@@ -460,25 +779,103 @@ export const docsDense = {
     description:
       'Renders a markdown string as Astryx-styled components. Use Markdown for user-generated content, AI responses, and documentation; it handles headings, lists, tables, code blocks, and citations with consistent styling.',
     bestPractices: [
-      { guidance: true, description: 'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.' },
-      { guidance: true, description: 'Use contentWidth to keep prose at a readable line length in wide layouts.' },
-      { guidance: true, description: 'Use inlinePlugins for custom shorthand patterns (issue refs, diff refs, mentions) instead of preprocessing the markdown string.' },
-      { guidance: true, description: 'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.' },
-      { guidance: false, description: 'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.' },
+      {
+        guidance: true,
+        description:
+          'Set headingLevelStart to match the page hierarchy, e.g. start at 3 if the markdown sits inside an h2 section.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use contentWidth to keep prose at a readable line length in wide layouts.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use plugins created by createMarkdownPlugin for reusable syntax, immutable AST transforms, and typed extension rendering. Keep the ordered list stable while its syntax configuration is unchanged.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownTextTransform for prose matching; it preserves code, links, images, citations, math, and accepted extension syntax as protected contexts. Provide requiredSubstrings only when they conservatively cover every possible match.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFenceTransform for declared code-fence languages with semantic data. createNode returns an owned block extension node; its standard plugin renderer and toText own presentation. components.code still wins, and a declined or failed proposal keeps the accessible, copyable CodeBlock fallback.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownSourceDecoration to attach non-visual metadata — search hits, review annotations — to the blocks a source range touches, and getMarkdownSourceDecorations to read it back in a later plugin. Decorations appear on the settled document rather than on partial streaming chunks, and never change rendering, copyable text, accessible names, ids, focus order, or navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Import parseMarkdownAst or parseInlineAst from @astryxdesign/core/Markdown/parser when server or React Server Component code needs to run plugins against the canonical readonly tree. The parser and plugin subpaths have no use-client boundary. The Markdown component remains client-owned, so function-bearing plugin entries must not be passed across an RSC serialization boundary.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use createMarkdownFrontmatter for typed document metadata. Its parse() method gives the host metadata directly; its plugin removes a complete leading block before rendering and withholds an unfinished block during streaming.',
+      },
+      {
+        guidance: true,
+        description:
+          "Import createMarkdownRemarkTransform from '@astryxdesign/core/Markdown/remark' only to reuse a synchronous transform-only Remark plugin; it stays out of every other bundle and unsupported behavior keeps the last valid document with one diagnostic.",
+      },
+      {
+        guidance: true,
+        description:
+          'Use inlinePlugins for prefixed identifiers, mentions, and other prose-only shorthand instead of preprocessing the markdown string.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide components.math only for documents that use dollar-delimited math; the renderer owns typesetting and accessible output.',
+      },
+      {
+        guidance: true,
+        description:
+          'Direct math parser calls use MathParseOptions and the explicit WithMath node unions; incremental calls also use createIncrementalState<true>() and IncrementalParseState<true>. Default calls keep the legacy unions.',
+      },
+      {
+        guidance: true,
+        description:
+          'Headings render id attributes matching useOutlineFromMarkdown ids; pair with Outline for hash navigation.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use Markdown for hand-authored layouts; use Text and Heading directly when you control the content.',
+      },
     ],
   },
   propDescriptions: {
     children: 'markdown string',
     density: "Block spacing. 'default'|'compact'. Default: 'default'.",
-    headingLevelStart: 'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',
-    isStreaming: 'Incremental parse + fade-in for streamed chunks. Default: false.',
-    onLinkClick: '(href, event) => void|false. Return false prevents navigation.',
-    sources: 'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',
-    citationStyle: "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",
-    contentWidth: 'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',
-    contentAlign: "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",
-    inlinePlugins: 'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code.',
-    autolink: "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",
+    headingLevelStart:
+      'Maps # to this heading level (1-6). Clamped to h6. Default: 1.',
+    isStreaming:
+      'Incremental parse + fade-in for streamed chunks. Default: false.',
+    onLinkClick:
+      '(href, event) => void|false. Return false prevents navigation.',
+    sources:
+      'Record<string, MarkdownSource>. Citation sources by ID. [id]/【id】 markers render as chips.',
+    citationStyle:
+      "'label'|'number'. label=chip w/ title+icon, number=compact badge. Default: 'label'.",
+    contentWidth:
+      'number|string. Max width for prose (headings, paragraphs, lists). Tables/code unconstrained.',
+    contentAlign:
+      "'start'|'center'. Prose alignment when contentWidth < container. Default: 'start'.",
+    plugins:
+      'readonly MarkdownPluginEntry[]. Ordered syntax, immutable AST transforms, and typed extension renderers from createMarkdownPlugin(). Narrow observed extensions with isMarkdownExtensionNode(); renderer callbacks are pure. Default: omitted or empty.',
+    inlinePlugins:
+      'MarkdownInlinePlugin[]. Regex matches in text nodes -> custom inline React elements. Skips inline/fenced code and math.',
+    autolink:
+      "'gfm'. Opt-in GFM autolinking: bare URLs (https?://, www.), <scheme:url>, <email>, user@host. Skips code, code blocks, existing links. Default: off.",
+    components:
+      'MarkdownComponents. Custom renderers; math({value, display}) opts into $…$/$$…$$ parsing. Renderer owns output and accessibility.',
     xstyle: 'stylex.create() for layout (margins, sizing).',
     className: 'CSS class. Prefer xstyle.',
     style: 'Inline styles. Prefer xstyle.',