;
diff --git a/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts b/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts
new file mode 100644
index 00000000..0d65e81e
--- /dev/null
+++ b/site/src/utils/docs/__tests__/renderInlineMarkdown.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { renderInlineMarkdown } from '../renderInlineMarkdown';
+
+describe('renderInlineMarkdown', () => {
+ it('returns plain text for a simple sentence', () => {
+ expect(renderInlineMarkdown('Whether the button is disabled.')).toBe('Whether the button is disabled.');
+ });
+
+ it('unwraps a single paragraph', () => {
+ const result = renderInlineMarkdown('Hello **world**.');
+ expect(result).not.toMatch(/^world');
+ });
+
+ it('preserves multiple paragraphs', () => {
+ const result = renderInlineMarkdown('First paragraph.\n\nSecond paragraph.');
+ expect(result).toContain(' {
+ const result = renderInlineMarkdown('Use `foo` here.');
+ expect(result).toContain(' {
+ const result = renderInlineMarkdown('**bold text**');
+ expect(result).toContain('bold text');
+ });
+
+ it('renders emphasized text', () => {
+ const result = renderInlineMarkdown('*italic text*');
+ expect(result).toContain('italic text');
+ });
+
+ it('renders links with correct classes', () => {
+ const result = renderInlineMarkdown('[link](https://example.com)');
+ expect(result).toContain('href="https://example.com"');
+ expect(result).toContain('underline');
+ expect(result).toContain('intent:no-underline');
+ });
+
+ it('renders unordered lists', () => {
+ const result = renderInlineMarkdown('- item one\n- item two');
+ expect(result).toContain(' {
+ const result = renderInlineMarkdown('1. first\n2. second');
+ expect(result).toContain(' {
+ const result = renderInlineMarkdown('# Heading');
+ expect(result).not.toContain(' {
+ const result = renderInlineMarkdown('before\n\n---\n\nafter');
+ expect(result).not.toContain(' {
+ const md = 'The volume level:\n\n- `0` — muted\n- `1` — max';
+ const result = renderInlineMarkdown(md);
+ expect(result).toContain(' {
+ const result = renderInlineMarkdown('```\nconst x = 1;\n```');
+ expect(result).toContain('${this.parser.parseInline(tokens)}
`;
+ },
+
+ list(token: Tokens.List) {
+ const tag = token.ordered ? 'ol' : 'ul';
+ const cls = token.ordered ? classes.ol : classes.ul;
+ const body = token.items.map((item) => this.listitem(item)).join('\n');
+ return `<${tag} class="${cls}">${body}`;
+ },
+
+ listitem(item: Tokens.ListItem) {
+ let body = this.parser.parse(item.tokens, !!item.loose);
+ if (!item.loose) {
+ body = body.replace(/^/, '').replace(/<\/p>$/, '');
+ }
+ return `
${body}`;
+ },
+
+ code({ text }) {
+ return `${text}`;
+ },
+
+ codespan({ text }) {
+ return `${text}`;
+ },
+
+ strong({ tokens }) {
+ return `${this.parser.parseInline(tokens)}`;
+ },
+
+ em({ tokens }) {
+ return `${this.parser.parseInline(tokens)}`;
+ },
+
+ link({ href, tokens }) {
+ return `${this.parser.parseInline(tokens)}`;
+ },
+
+ // --- Unsupported elements — downgrade or suppress ---
+
+ heading({ tokens }) {
+ return `${this.parser.parseInline(tokens)}
`;
+ },
+
+ blockquote({ tokens }) {
+ return this.parser.parse(tokens);
+ },
+
+ hr() {
+ return '';
+ },
+
+ image({ href, text }) {
+ return text || href;
+ },
+
+ table() {
+ return '';
+ },
+
+ tablerow() {
+ return '';
+ },
+
+ tablecell() {
+ return '';
+ },
+};
+
+const marked = new Marked({ renderer });
+
+/**
+ * Unwrap a single `` wrapper so simple descriptions sit inline.
+ *
+ * If the output is a lone `
…
` with no other block-level
+ * elements, strip the wrapper and return only the inner content.
+ */
+function unwrapSingleParagraph(html: string): string {
+ const trimmed = html.trim();
+ const match = trimmed.match(/^([\s\S]*)<\/p>$/);
+ if (match && !trimmed.includes('