@tanstack/markdown 0.0.7 → 0.0.9

package/README.md

@@ -1,8 +1,15 @@
 # TanStack Markdown
 
-A tiny, fast, deterministic Markdown renderer for blogs and documentation.
+A tiny, fast, deterministic Markdown parser and renderer for blogs and documentation.
 
-The current browser bundles are 4.6 KB gzip for the parser, 6.4 KB for HTML rendering, and 6.3 KB for the React adapter. The package has no runtime dependencies and does not bundle syntax highlighting.
+- 4.6 KB gzip parser
+- 6.4 KB gzip HTML renderer
+- 6.3 KB gzip React adapter
+- 6.3 KB gzip Octane adapter
+- zero runtime dependencies
+- serializable AST
+- safe defaults for raw HTML and executable URLs
+- optional docs extensions and external syntax highlighting
 
 ```bash
 pnpm add @tanstack/markdown
@@ -22,13 +29,29 @@ export function Article({ source }: { source: string }) {
 }
 ```
 
-Raw HTML is escaped and executable link protocols are removed by default. `allowHtml` and highlighter output are explicit trusted-content boundaries.
+```tsrx
+import { Markdown } from '@tanstack/markdown/octane'
 
-## Scope
+export function Article({ source }: { source: string }) @{
+  <Markdown>{source}</Markdown>
+}
+```
+
+TanStack Markdown targets controlled technical content. It supports the Markdown used by blogs and docs, then spends its remaining complexity budget on deterministic output, renderer parity, malformed-input resilience, and small entry points. It is intentionally not a complete CommonMark, GFM, MDX, or general content-processing implementation.
 
-This is deliberately not a complete CommonMark, GFM, MDX, or content-processing implementation. It implements the syntax used by technical blogs and documentation, then spends its complexity budget on deterministic output, safe defaults, React/HTML parity, malformed-input resilience, and small entry points.
+## Documentation
 
-See the [docs Markdown profile](./docs/profile.md) for the supported contract and deliberate non-goals.
+- [Overview](./docs/overview.md)
+- [Installation](./docs/installation.md)
+- [Quick Start](./docs/quick-start.md)
+- [Comparison](./docs/comparison.md)
+- [Syntax Profile](./docs/core-concepts/syntax-profile.md)
+- [React Guide](./docs/guides/react.md)
+- [Octane Guide](./docs/guides/octane.md)
+- [Syntax Highlighting](./docs/guides/syntax-highlighting.md)
+- [Extensions](./docs/guides/extensions.md)
+- [API Reference](./docs/reference/index.md)
+- [Architecture](./docs/project/architecture.md)
 
 ## Verification
 
@@ -36,17 +59,15 @@ See the [docs Markdown profile](./docs/profile.md) for the supported contract an
 pnpm run verify
 ```
 
-To include downstream repositories in the corpus gate:
+To include downstream content in the corpus gate:
 
 ```bash
-MARKDOWN_CORPUS_DIRS=../tanstack.com/src/blog:../tanstack.com/docs pnpm run test:corpus
+MARKDOWN_CORPUS_DIRS=../tanstack.com/src/blog:../tanstack.com/docs \
+  pnpm run test:corpus
 ```
 
-## Reports
+Generated reports:
 
 - [Bundle sizes](./reports/sizes.md)
 - [Benchmarks](./reports/benchmarks.md)
 - [CommonMark compatibility accounting](./reports/conformance.md)
-- [Audit](./docs/audit.md)
-- [Spec and API](./docs/spec.md)
-- [Extensions](./docs/extensions.md)

package/dist/octane.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentBody, ElementDescriptor, OctaneNode } from 'octane';
+import type { BlockNode, InlineNode, MarkdownInput, RenderOptions } from './types.js';
+type ComponentMap = Partial<Record<string, string | ComponentBody<any>>>;
+export interface MarkdownOctaneOptions extends RenderOptions {
+    components?: ComponentMap;
+}
+export interface MarkdownProps extends MarkdownOctaneOptions {
+    children: MarkdownInput;
+}
+export declare function Markdown({ children, ...options }: MarkdownProps): ElementDescriptor;
+export declare function renderMarkdownOctane(input: MarkdownInput, options?: MarkdownOctaneOptions): OctaneNode[];
+export declare function renderBlockOctane(node: BlockNode, options?: MarkdownOctaneOptions, key?: string): ElementDescriptor;
+export declare function renderInlineOctane(node: InlineNode, options?: MarkdownOctaneOptions, key?: string): OctaneNode;
+export {};
+//# sourceMappingURL=octane.d.ts.map

package/dist/octane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"octane.d.ts","sourceRoot":"","sources":["../src/octane.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAmC,UAAU,EAAE,aAAa,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAA;AAErI,KAAK,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAExE,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,UAAU,CAAC,EAAE,YAAY,CAAA;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,qBAAqB;IAC1D,QAAQ,EAAE,aAAa,CAAA;CACxB;AAED,wBAAgB,QAAQ,CAAC,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,EAAE,aAAa,GAAG,iBAAiB,CAEnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,UAAU,EAAE,CAG5G;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,qBAA0B,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,iBAAiB,CA+DvH;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAwClH"}

package/dist/octane.js

@@ -0,0 +1,189 @@
+import { Fragment, createElement } from 'octane';
+import { parseMarkdown } from './parser.js';
+export function Markdown({ children, ...options }) {
+    return createElement(Fragment, null, ...renderMarkdownOctane(children, options));
+}
+export function renderMarkdownOctane(input, options = {}) {
+    const document = typeof input === 'string' ? parseMarkdown(input, options) : input;
+    return document.children.map((node, index) => renderBlockOctane(node, options, `b:${index}`));
+}
+export function renderBlockOctane(node, options = {}, key) {
+    switch (node.type) {
+        case 'heading':
+            return h(options, `h${node.depth}`, { key, ...(node.id ? { id: node.id } : {}), ...(node.framework ? { 'data-framework': node.framework } : {}) }, renderInlines(node.children, options), renderHeadingAnchorOctane(node.id, options));
+        case 'paragraph':
+            return h(options, 'p', { key }, renderInlines(node.children, options));
+        case 'code':
+            return renderCodeBlockOctane(node, options, key);
+        case 'list': {
+            const tag = node.ordered ? 'ol' : 'ul';
+            return h(options, tag, { key, ...(node.ordered && node.start && node.start !== 1 ? { start: node.start } : {}) }, node.items.map((item, index) => h(options, 'li', { key: index }, renderListItemChildrenOctane(item.children, item.checked, node.loose, options, `${index}`))));
+        }
+        case 'blockquote':
+            return h(options, 'blockquote', { key }, node.children.map((child, index) => renderBlockOctane(child, options, `${key}:${index}`)));
+        case 'table':
+            return h(options, 'table', { key }, h(options, 'thead', null, h(options, 'tr', null, node.header.map((cell, index) => renderTableCellOctane('th', cell, node.align[index], options, index)))), node.rows.length
+                ? h(options, 'tbody', null, node.rows.map((row, rowIndex) => h(options, 'tr', { key: rowIndex }, row.map((cell, index) => renderTableCellOctane('td', cell, node.align[index], options, index)))))
+                : null);
+        case 'footnotes':
+            return renderFootnotesOctane(node.items, options, key);
+        case 'thematicBreak':
+            return h(options, 'hr', { key });
+        case 'html':
+            return options.allowHtml
+                ? h(options, 'div', { key, dangerouslySetInnerHTML: { __html: node.value } })
+                : h(options, 'p', { key }, node.value);
+        case 'callout':
+            return h(options, 'div', { key, className: `markdown-alert markdown-alert-${node.kind.toLowerCase()}` }, h(options, 'p', { className: 'markdown-alert-title' }, node.title), h(options, 'div', { className: 'markdown-alert-content' }, node.children.map((child, index) => renderBlockOctane(child, options, `${key}:${index}`))));
+        case 'component':
+            return renderComponentOctane(node, options, key);
+    }
+}
+export function renderInlineOctane(node, options = {}, key) {
+    switch (node.type) {
+        case 'text':
+            return node.value;
+        case 'inlineCode':
+            return h(options, 'code', { key }, node.value);
+        case 'strong':
+            return h(options, 'strong', { key }, renderInlines(node.children, options));
+        case 'emphasis':
+            return h(options, 'em', { key }, renderInlines(node.children, options));
+        case 'strike':
+            return h(options, 'del', { key }, renderInlines(node.children, options));
+        case 'footnoteReference':
+            return h(options, 'sup', { key }, h(options, 'a', {
+                id: `user-content-fnref-${footnoteReferenceId(node)}`,
+                'data-footnote-ref': '',
+                'aria-describedby': 'footnote-label',
+                href: `#user-content-fn-${node.id}`,
+            }, node.number));
+        case 'link':
+            return h(options, 'a', { key, href: node.href, ...(node.title ? { title: node.title } : {}) }, renderInlines(node.children, options));
+        case 'image':
+            return h(options, 'img', { key, src: node.src, alt: node.alt, ...(node.title ? { title: node.title } : {}) });
+        case 'break':
+            return h(options, 'br', { key });
+        case 'inlineHtml':
+            return options.allowHtml
+                ? h(options, 'span', { key, dangerouslySetInnerHTML: { __html: node.value } })
+                : node.value;
+    }
+}
+function renderInlines(nodes, options) {
+    return nodes.map((node, index) => renderInlineOctane(node, options, `i:${index}`));
+}
+function renderCodeBlockOctane(node, options, key) {
+    const lang = node.lang ?? 'plaintext';
+    const highlighter = options.highlighter;
+    const content = highlighter ? undefined : node.value;
+    const highlighted = highlighter
+        ? {
+            dangerouslySetInnerHTML: {
+                __html: highlighter(node.value, lang, {
+                    ...(node.highlightLines && { highlightLines: node.highlightLines }),
+                    ...(options.codeLineNumbers !== undefined && { lineNumbers: options.codeLineNumbers }),
+                }),
+            },
+        }
+        : undefined;
+    const pre = h(options, 'pre', {
+        className: 'tm-code',
+        'data-lang': lang,
+        ...(node.title ? { 'data-code-title': node.title } : {}),
+        ...(node.file ? { 'data-filename': node.file } : {}),
+        ...(node.framework ? { 'data-framework': node.framework } : {}),
+    }, h(options, 'code', { className: `language-${lang}`, ...highlighted }, content));
+    if (!node.title)
+        return h(options, Fragment, { key }, pre);
+    return h(options, 'figure', { key, className: 'tm-code-frame', 'data-lang': lang }, h(options, 'figcaption', null, node.title), pre);
+}
+function renderListItemChildrenOctane(children, checked, loose, options, key) {
+    const [first, ...rest] = children;
+    const task = checked === undefined
+        ? []
+        : [
+            h(options, 'input', {
+                key: `${key}:checkbox`,
+                type: 'checkbox',
+                disabled: true,
+                checked,
+                readOnly: true,
+            }),
+            ' ',
+        ];
+    if (first?.type === 'paragraph') {
+        const content = [...task, ...renderInlines(first.children, options)];
+        return [
+            ...(loose ? [h(options, 'p', { key: `${key}:paragraph` }, content)] : content),
+            ...rest.flatMap((child, childIndex) => renderListChildOctane(child, loose, options, `${key}:${childIndex + 1}`)),
+        ];
+    }
+    return [...task, ...children.flatMap((child, childIndex) => renderListChildOctane(child, loose, options, `${key}:${childIndex}`))];
+}
+function renderListChildOctane(child, loose, options, key) {
+    return !loose && child.type === 'paragraph' ? renderInlines(child.children, options) : [renderBlockOctane(child, options, key)];
+}
+function renderTableCellOctane(tag, cell, align, options, key) {
+    return h(options, tag, { key, ...(align ? { style: { textAlign: align } } : {}) }, renderInlines(cell.children, options));
+}
+function renderFootnotesOctane(items, options, key) {
+    return h(options, 'section', { key, 'data-footnotes': '', className: 'footnotes' }, h(options, 'h2', { id: 'footnote-label', className: 'sr-only' }, 'Footnotes', renderHeadingAnchorOctane('footnote-label', options)), h(options, 'ol', null, items.map(item => h(options, 'li', { key: item.id, id: `user-content-fn-${item.id}` }, renderFootnoteItemOctane(item, options)))));
+}
+function renderFootnoteItemOctane(item, options) {
+    const lastIndex = item.children.length - 1;
+    const backrefs = renderFootnoteBackrefsOctane(item, options);
+    if (lastIndex < 0)
+        return [h(options, 'p', { key: 'backref-wrapper' }, backrefs.slice(1))];
+    return item.children.map((child, index) => {
+        if (index === lastIndex && child.type === 'paragraph') {
+            return h(options, 'p', { key: index }, renderInlines(child.children, options), backrefs);
+        }
+        return renderBlockOctane(child, options, `${index}`);
+    });
+}
+function renderFootnoteBackrefsOctane(item, options) {
+    const result = [];
+    for (let index = 1; index <= (item.referenceCount ?? 1); index++) {
+        const referenceId = index === 1 ? item.id : `${item.id}-${index}`;
+        const label = index === 1 ? `${item.number}` : `${item.number}-${index}`;
+        result.push(' ', h(options, 'a', {
+            key: index,
+            'data-footnote-backref': '',
+            'aria-label': `Back to reference ${label}`,
+            className: 'data-footnote-backref',
+            href: `#user-content-fnref-${referenceId}`,
+        }, '\u21a9'));
+    }
+    return result;
+}
+function footnoteReferenceId(node) {
+    return node.referenceIndex && node.referenceIndex > 1 ? `${node.id}-${node.referenceIndex}` : node.id;
+}
+function h(options, tag, props, ...children) {
+    const component = typeof tag === 'string' ? options.components?.[tag] ?? tag : tag;
+    return createElement(component, props ?? undefined, ...children);
+}
+function renderComponentOctane(node, options, key) {
+    const tag = node.tagName ?? 'md-comment-component';
+    const props = {
+        ...(node.properties ?? {}),
+    };
+    if (!node.tagName) {
+        props['data-component'] = node.name;
+        if (!props['data-attributes'])
+            props['data-attributes'] = JSON.stringify(node.attributes);
+    }
+    return h(options, tag, { key, ...props }, node.children.map((child, index) => renderBlockOctane(child, options, `${key}:${index}`)));
+}
+function renderHeadingAnchorOctane(id, options) {
+    if (!id || !options.headingAnchors)
+        return null;
+    const anchorOptions = typeof options.headingAnchors === 'object' ? options.headingAnchors : {};
+    return h(options, 'a', {
+        href: `#${id}`,
+        'aria-hidden': anchorOptions.ariaHidden ?? true,
+        className: anchorOptions.className ?? 'anchor-heading anchor-heading-link',
+        tabIndex: anchorOptions.tabIndex ?? -1,
+    }, anchorOptions.content ?? '#');
+}

package/dist/parser.js

@@ -368,9 +368,13 @@ function extractDefinitions(lines) {
                 }
                 continue;
             }
-            const definition = line.match(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(\S+)[ \t]*$/);
+            const definition = line.match(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(\S+)(?:[ \t]+(?:"([^"]*)"|'([^']*)'|\(([^)]*)\)))?[ \t]*$/);
             if (definition) {
-                references[normalizeReferenceLabel(definition[1])] = { href: definition[2].replace(/^<|>$/g, '') };
+                const title = definition[3] ?? definition[4] ?? definition[5];
+                references[normalizeReferenceLabel(definition[1])] = {
+                    href: definition[2].replace(/^<|>$/g, ''),
+                    ...(title !== undefined ? { title } : {}),
+                };
                 index++;
                 continue;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/markdown",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "description": "A tiny, fast, deterministic Markdown renderer for blogs and documentation.",
   "license": "MIT",
@@ -27,6 +27,10 @@
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
     },
+    "./octane": {
+      "types": "./dist/octane.d.ts",
+      "import": "./dist/octane.js"
+    },
     "./extensions/callouts": {
       "types": "./dist/extensions/callouts.d.ts",
       "import": "./dist/extensions/callouts.js"
@@ -56,9 +60,13 @@
     "access": "public"
   },
   "peerDependencies": {
+    "octane": ">=0.1.12",
     "react": ">=18"
   },
   "peerDependenciesMeta": {
+    "octane": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
@@ -74,6 +82,7 @@
     "markdown-wasm": "^1.2.0",
     "marked": "^18.0.5",
     "micromark": "^4.0.2",
+    "octane": "0.1.12",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "rehype-stringify": "^10.0.1",
@@ -89,10 +98,11 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:corpus": "vitest run tests/corpus.test.tsx",
+    "docs:verify": "node scripts/verify-docs.mjs",
     "conformance": "tsx scripts/conformance.ts",
     "bench": "tsx scripts/bench.ts",
     "size": "tsx scripts/measure-size.ts",
     "research": "pnpm run conformance && pnpm run size && pnpm run bench",
-    "verify": "pnpm test && pnpm run typecheck && pnpm run build && pnpm run research && pnpm pack --dry-run"
+    "verify": "pnpm test && pnpm run typecheck && pnpm run build && pnpm run docs:verify && pnpm run research && pnpm pack --dry-run"
   }
 }