Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Markdown docs page and block examples (#1679)

Ted McDonald72c4f6874e2f
diff --git a/packages/cli/templates/blocks/components/Markdown/MarkdownCitedContent.doc.mjs b/packages/cli/templates/blocks/components/Markdown/MarkdownCitedContent.doc.mjs
index 4714dc44a1..d24f5fed47 100644
--- a/packages/cli/templates/blocks/components/Markdown/MarkdownCitedContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/Markdown/MarkdownCitedContent.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Markdown — Cited Content',
- description:
- 'Markdown with inline citation references linked to external sources.',
+ description: 'Markdown with citation chips linked to external sources',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Markdown'],
diff --git a/packages/cli/templates/blocks/components/Markdown/MarkdownCompactAIResponse.doc.mjs b/packages/cli/templates/blocks/components/Markdown/MarkdownCompactAIResponse.doc.mjs
index 557e3ff87f..40b99f1463 100644
--- a/packages/cli/templates/blocks/components/Markdown/MarkdownCompactAIResponse.doc.mjs
+++ b/packages/cli/templates/blocks/components/Markdown/MarkdownCompactAIResponse.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Markdown — Compact AI Response',
- description:
- 'AI-style compact markdown with shifted headings, code, and blockquotes.',
+ description: 'Compact markdown styled for AI responses with shifted heading levels',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Markdown'],
diff --git a/packages/cli/templates/blocks/components/Markdown/MarkdownDataTable.doc.mjs b/packages/cli/templates/blocks/components/Markdown/MarkdownDataTable.doc.mjs
index cfd46e7b73..2f62b36f78 100644
--- a/packages/cli/templates/blocks/components/Markdown/MarkdownDataTable.doc.mjs
+++ b/packages/cli/templates/blocks/components/Markdown/MarkdownDataTable.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Markdown — Data Table',
- description:
- 'Markdown-rendered comparison table with aligned columns and mixed data.',
+ description: 'Comparison table rendered from a markdown string',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Markdown'],
diff --git a/packages/cli/templates/blocks/components/Markdown/MarkdownRichContent.doc.mjs b/packages/cli/templates/blocks/components/Markdown/MarkdownRichContent.doc.mjs
index cbf0195280..6742ab9a98 100644
--- a/packages/cli/templates/blocks/components/Markdown/MarkdownRichContent.doc.mjs
+++ b/packages/cli/templates/blocks/components/Markdown/MarkdownRichContent.doc.mjs
@@ -2,8 +2,7 @@
export const doc = {
type: 'block',
name: 'Markdown — Rich Content',
- description:
- 'Full-featured markdown rendering with headings, lists, code blocks, tables, and blockquotes.',
+ description: 'Markdown with headings, lists, code blocks, tables, blockquotes, and task lists',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Markdown'],
diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjs
index b8e8297da7..d6046fb466 100644
--- a/packages/core/src/Markdown/Markdown.doc.mjs
+++ b/packages/core/src/Markdown/Markdown.doc.mjs
@@ -103,11 +103,11 @@ export const docs = {
},
usage: {
description:
- 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ 'Renders a markdown string as XDS-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 fit the surrounding page hierarchy when embedding markdown within a section.' },
- { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
- { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
+ { 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: false, description: 'Use Markdown for hand-authored layouts — use XDSText and XDSHeading directly when you control the content.' },
],
},
};
@@ -201,26 +201,26 @@ export const docsZh = {
},
usage: {
description:
- 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ 'Renders a markdown string as XDS-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 fit the surrounding page hierarchy when embedding markdown within a section.' },
- { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
- { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
+ { 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: false, description: 'Use Markdown for hand-authored layouts — use XDSText and XDSHeading directly when you control the content.' },
],
},
};
export const docsDense = {
n: 'Markdown',
- d: 'Renders markdown string as XDS components. Headings, bold, italic, code, lists, tables, links, blockquotes, task lists. Streaming with fade-in animation.',
+ d: 'Renders markdown string as XDS-styled components. Use for user-generated content, AI responses, docs. Headings, lists, tables, code, citations w/ consistent styling.',
kw: ['markdown', 'rich text', 'prose', 'renderer', 'streaming', 'markup', 'md'],
usage: {
description:
- 'Markdown renders a markdown string as XDS-styled components with support for headings, lists, tables, code blocks, and more. Use it for displaying user-generated or AI-streamed content with consistent design-system styling.',
+ 'Renders a markdown string as XDS-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 fit the surrounding page hierarchy when embedding markdown within a section.' },
- { guidance: true, description: 'Use contentWidth to constrain prose to a readable line length in wide layouts.' },
- { guidance: false, description: 'Use Markdown for hand-authored rich text layouts — use XDSText and heading components directly instead.' },
+ { 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: false, description: 'Use Markdown for hand-authored layouts — use XDSText and XDSHeading directly when you control the content.' },
],
},
p: {