Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { createProcessor } from '@mdx-js/mdx'; |
| 2 | import remarkGfm from 'remark-gfm'; |
| 3 | import { toString } from 'mdast-util-to-string'; |
| 4 | import type { Root, RootContent } from 'mdast'; |
| 5 | import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx'; |
| 6 | |
| 7 | export type ExampleNode = Root | RootContent; |
| 8 | type JsxElement = MdxJsxFlowElement | MdxJsxTextElement; |
| 9 | const markdownProcessor = createProcessor({ format: 'md', remarkPlugins: [remarkGfm] }); |
| 10 | const mdxProcessor = createProcessor({ format: 'mdx', remarkPlugins: [remarkGfm] }); |
| 11 | |
| 12 | /** Frontmatter is metadata, not MDX; blanking it preserves source positions. */ |
| 13 | export function parseExampleDocument(source: string, path: string): Root { |
| 14 | const body = source.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, (frontmatter) => |
| 15 | frontmatter.replace(/[^\n]/g, ' '), |
| 16 | ); |
| 17 | return (path.endsWith('.md') ? markdownProcessor : mdxProcessor).parse(body); |
| 18 | } |
| 19 | |
| 20 | /** Read literal JSX values from the parsed expression, never rendered source text. */ |
| 21 | export function attributeValue(node: JsxElement, name: string): string | string[] | undefined { |
| 22 | const attribute = node.attributes.find((item) => item.type === 'mdxJsxAttribute' && item.name === name); |
| 23 | if (!attribute || attribute.type !== 'mdxJsxAttribute') return undefined; |
| 24 | if (typeof attribute.value === 'string') return attribute.value; |
| 25 | const statement = attribute.value?.data?.estree?.body[0]; |
| 26 | if (statement?.type !== 'ExpressionStatement') return undefined; |
| 27 | const expression = statement.expression; |
| 28 | if (expression.type === 'Literal' && typeof expression.value === 'string') return expression.value; |
| 29 | if (expression.type !== 'ArrayExpression') return undefined; |
| 30 | const items: string[] = []; |
| 31 | for (const item of expression.elements) { |
| 32 | if (item?.type !== 'Literal' || typeof item.value !== 'string') return undefined; |
| 33 | items.push(item.value); |
| 34 | } |
| 35 | return items; |
| 36 | } |
| 37 | |
| 38 | export type MarkdownLanguageGroup = { |
| 39 | start: number; |
| 40 | end: number; |
| 41 | line: number; |
| 42 | tabs: { value: string; source: string; line: number }[]; |
| 43 | }; |
| 44 | |
| 45 | const isEndLanguages = (node: RootContent | undefined) => |
| 46 | node?.type === 'html' && /^<!--\s*end-languages\s*-->$/.test(node.value.trim()); |
| 47 | |
| 48 | /** |
| 49 | * Plain Markdown uses consecutive Python / TypeScript / API headings. The last |
| 50 | * option runs to the next heading unless `<!-- end-languages -->` closes the |
| 51 | * group first; the marker belongs to neither the options nor the shared prose. |
| 52 | */ |
| 53 | export function markdownLanguageGroups(source: string): MarkdownLanguageGroup[] { |
| 54 | const nodes = parseExampleDocument(source, 'example.md').children; |
| 55 | const groups: MarkdownLanguageGroup[] = []; |
| 56 | for (let index = 0; index < nodes.length; index++) { |
| 57 | const first = nodes[index]; |
| 58 | if (first.type !== 'heading' || toString(first) !== 'Python') continue; |
| 59 | const group: MarkdownLanguageGroup = { |
| 60 | start: first.position?.start.offset ?? 0, |
| 61 | end: source.length, |
| 62 | line: first.position?.start.line ?? 1, |
| 63 | tabs: [], |
| 64 | }; |
| 65 | let cursor = index; |
| 66 | while (cursor < nodes.length) { |
| 67 | const heading = nodes[cursor]; |
| 68 | if (heading.type !== 'heading' || heading.depth !== first.depth || |
| 69 | !['Python', 'TypeScript', 'API'].includes(toString(heading))) break; |
| 70 | let end = cursor + 1; |
| 71 | while (end < nodes.length) { |
| 72 | const next = nodes[end]; |
| 73 | if (next.type === 'heading' && next.depth <= first.depth) break; |
| 74 | if (isEndLanguages(next)) break; |
| 75 | end++; |
| 76 | } |
| 77 | const contentStart = heading.position?.end.offset ?? 0; |
| 78 | const contentEnd = nodes[end]?.position?.start.offset ?? source.length; |
| 79 | group.tabs.push({ value: toString(heading), source: source.slice(contentStart, contentEnd), line: heading.position?.start.line ?? 1 }); |
| 80 | group.end = contentEnd; |
| 81 | cursor = end; |
| 82 | if (isEndLanguages(nodes[end])) { |
| 83 | group.end = nodes[end].position?.end.offset ?? contentEnd; |
| 84 | cursor = end + 1; |
| 85 | break; |
| 86 | } |
| 87 | } |
| 88 | groups.push(group); |
| 89 | index = cursor - 1; |
| 90 | } |
| 91 | return groups; |
| 92 | } |
| 93 | |
| 94 | /** |
| 95 | * Converts real tab delimiters and link cards independently; nested labels and |
| 96 | * fenced literals survive. Cards are delimited by the parser, not by regexes |
| 97 | * that could run from one card's `title` to a later card's `description`. |
| 98 | */ |
| 99 | export function componentsToMarkdown(source: string): string { |
| 100 | if (!/<(?:Tabs|Tab|TabsContent|Card)\b/.test(source)) return source; |
| 101 | const changes: { start: number; end: number; text: string }[] = []; |
| 102 | const visit = (node: ExampleNode) => { |
| 103 | if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') { |
| 104 | const start = node.position?.start.offset; |
| 105 | const end = node.position?.end.offset; |
| 106 | if (start !== undefined && end !== undefined && ['Tabs', 'Tab', 'TabsContent', 'TabsList', 'TabsTrigger'].includes(node.name ?? '')) { |
| 107 | const value = attributeValue(node, 'value'); |
| 108 | const label = (node.name === 'Tab' || node.name === 'TabsContent') && typeof value === 'string' ? `\n**${value}:**\n` : ''; |
| 109 | if (!node.children.length || node.name === 'TabsList' || node.name === 'TabsTrigger') { |
| 110 | changes.push({ start, end, text: label }); |
| 111 | return; |
| 112 | } |
| 113 | changes.push({ start, end: node.children[0].position?.start.offset ?? start, text: label }); |
| 114 | changes.push({ start: node.children.at(-1)?.position?.end.offset ?? end, end, text: '\n' }); |
| 115 | } else if (start !== undefined && end !== undefined && node.name === 'Card') { |
| 116 | const title = attributeValue(node, 'title'); |
| 117 | const href = attributeValue(node, 'href'); |
| 118 | const description = attributeValue(node, 'description'); |
| 119 | if (typeof title === 'string' && typeof href === 'string') { |
| 120 | const link = `- [${title}](${href})`; |
| 121 | if (!node.children.length) { |
| 122 | changes.push({ start, end, text: typeof description === 'string' ? `${link}: ${description}` : link }); |
| 123 | return; |
| 124 | } |
| 125 | changes.push({ start, end: node.children[0].position?.start.offset ?? start, text: `${link}: ` }); |
| 126 | changes.push({ start: node.children.at(-1)?.position?.end.offset ?? end, end, text: '' }); |
| 127 | } |
| 128 | } |
| 129 | } |
| 130 | if ('children' in node) for (const child of node.children) visit(child); |
| 131 | }; |
| 132 | visit(parseExampleDocument(source, 'page.mdx')); |
| 133 | let result = source; |
| 134 | for (const change of changes.sort((a, b) => b.start - a.start)) { |
| 135 | result = result.slice(0, change.start) + change.text + result.slice(change.end); |
| 136 | } |
| 137 | return result; |
| 138 | } |