@readme/markdown 15.2.0 → 15.3.0

package/README.md

@@ -99,6 +99,7 @@ Extends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)
 - **`safeMode`** (`boolean`, optional)—extract script tags from `HTMLBlock`s
 - **`components`** (`Record<string, string>`, optional)—an object of tag names to mdx.
 - **`copyButtons`** (`Boolean`, optional) — add a copy button to code blocks
+- **`hardBreaks`** (`boolean`, optional)—render every newline as a `<br>`. `mdxish` defaults to `true`
 
 ### `RunOpts`
 

package/dist/lib/mdxish.d.ts

@@ -3,6 +3,15 @@ import type { Root } from 'hast';
 import type { Root as MdastRoot } from 'mdast';
 export interface MdxishOpts {
     components?: CustomComponents;
+    /**
+     * Whether a single newline (\n) renders as a `<br>`. Defaults to `true`, matching legacy rdmd.
+     * Turn it off for CommonMark semantics, where only a blank line breaks — what content
+     * soft-wrapped to a line-length limit (OpenAPI descriptions, linted markdown) expects.
+     *
+     * Only applies to `mdxish()`; `mdxishAstProcessor` never hard-breaks its MDAST.
+     * There's no use for it right now but it can be revisited if needed.
+     */
+    hardBreaks?: boolean;
     newEditorTypes?: boolean;
     /**
      * When enabled, the pipeline ignores all expression syntax `{...}`.

package/dist/main.js

@@ -11423,7 +11423,7 @@ module.exports = function () {
 
 /***/ },
 
-/***/ 8071
+/***/ 5168
 (module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -75799,6 +75799,7 @@ var allCSS2RNProps = __webpack_unused_export__ = flatten([allProps, CSS2RNProps]
 
 
 
+
 /**
  * Extract word boundaries from camelCase strings (e.g., "borderWidth" -> ["border", "width"])
  */
@@ -75878,10 +75879,43 @@ const CUSTOM_PROP_BOUNDARIES = [
  */
 const RUNTIME_COMPONENT_TAGS = new Set(['Variable', 'variable', 'html-block', 'rdme-pin']);
 /**
- * Standard HTML tags that should never be treated as custom components.
- * Uses the html-tags package, converted to a Set<string> for efficient lookups.
+ * Elements that are not actually standard HTML tags, or those that we intentionally
+ * don't want to treat as one & is mute to check with. These include:
+ * - SVG/MathML descendants
+ * - Namespaced foreign content
+ * - `image`, which the HTML tree builder rewrites to `img`
+ * Most of these are bundled in parse5's `TAG_NAMES` set, but we can also add a few more.
+ */
+const NON_STANDARD_TAGS = new Set([
+    'annotation-xml',
+    'desc',
+    'foreignObject',
+    'image',
+    'malignmark',
+    'mglyph',
+    'mi',
+    'mn',
+    'mo',
+    'ms',
+    'mtext',
+]);
+/**
+ * Standard HTML tags list.
+ * A use case of this is to differentiate custom components tag vs standard HTML tags.
+ *
+ * Unioned from:
+ * - `html-tags`: All modern spec HTML elements
+ * - parse5's `TAG_NAMES`: Elements the HTML tree-construction algorithm has to special-case
+ *   This includes obsolete tags that are still rendered by browsers.
+ * - NON_STANDARD_TAGS: We've had to filter because currently parse5's `TAG_NAMES` set over-enumerates
+ *   tags that are not actually standard HTML tags. It also allows custom tags to be filtered out.
  */
-const STANDARD_HTML_TAGS = new Set(html_tags_namespaceObject);
+const STANDARD_HTML_TAGS = new Set([
+    ...html_tags_namespaceObject,
+    ...Object.values(TAG_NAMES),
+    'acronym', // Obselete tag not included either of the above sources. Add here if we have missed any.
+    'blink',
+].filter(tag => !NON_STANDARD_TAGS.has(tag)));
 /**
  * Table structural tags. Blank lines inside these carry deliberate meaning for
  * `mdxishTables` (e.g. splitting cell content into paragraphs, or deciding
@@ -101458,27 +101492,6 @@ const mdastV6 = (doc, { rdmd }) => {
 };
 /* harmony default export */ const lib_mdastV6 = (mdastV6);
 
-;// ./processor/compile/anchor.ts
-
-
-const anchor_anchor = (node) => {
-    const { href, label, target, title } = getHProps(node);
-    const attrs = {
-        ...(label && { label }),
-        ...(target && { target }),
-        href: href ?? '',
-        ...(title && { title }),
-    };
-    // Serialize children (phrasing content) back to markdown
-    // Wrap in paragraph to satisfy RootContent type requirement
-    const children = toMarkdown({
-        type: 'paragraph',
-        children: node.children,
-    }).trim();
-    return `<Anchor ${formatProps(attrs)}>${children}</Anchor>`;
-};
-/* harmony default export */ const compile_anchor = (anchor_anchor);
-
 ;// ./processor/compile/callout.ts
 
 const callout = (node, _, state, info) => {
@@ -101636,7 +101649,6 @@ const compile_text_text = (node, parent, state, info) => {
 
 
 
-
 function compilers(mdxish = false) {
     const data = this.data();
     const toMarkdownExtensions = data.toMarkdownExtensions || (data.toMarkdownExtensions = []);
@@ -101656,7 +101668,6 @@ function compilers(mdxish = false) {
         plain: compile_plain,
         yaml: compile_compatibility,
         // needed only for mdxish
-        ...(mdxish && { [NodeTypes.anchor]: compile_anchor }),
         ...(mdxish && { list: compile_list }),
         ...(mdxish && { listItem: list_item }),
         ...(mdxish && { text: compile_text }),
@@ -103541,6 +103552,39 @@ const mdxComponentHandlers = {
     [NodeTypes.htmlBlock]: htmlBlockHandler,
 };
 
+;// ./processor/transform/mdxish/anchor-to-jsx.ts
+
+
+
+/**
+ * Serializes mdxish anchors to JSX `<Anchor>` syntax. Handing the node to
+ * `mdast-util-mdx-jsx` runs the label through the document's own serializer
+ * state, so readme nodes (variables, emoji, glossary) reach their handlers.
+ */
+const mdxishAnchorToJsx = () => tree => {
+    visit(tree, NodeTypes.anchor, (node, index, parent) => {
+        if (!parent || index === undefined)
+            return;
+        const { href, label, target, title } = getHProps(node);
+        const jsx = {
+            type: 'mdxJsxTextElement',
+            name: 'Anchor',
+            // An anchor always renders an `href`, even an empty one, so it's built
+            // directly rather than through `toAttributes`, which drops empty values.
+            attributes: [
+                ...toAttributes({ label, target }),
+                { type: 'mdxJsxAttribute', name: 'href', value: href ?? '' },
+                ...toAttributes({ title }),
+            ],
+            children: node.children,
+            position: node.position,
+        };
+        parent.children[index] = jsx;
+    });
+    return tree;
+};
+/* harmony default export */ const anchor_to_jsx = (mdxishAnchorToJsx);
+
 ;// ./processor/transform/mdxish/callout-to-jsx.ts
 
 
@@ -105341,8 +105385,11 @@ var variable_default = /*#__PURE__*/__webpack_require__.n(variable_);
 const HTML_TAG_RE = /<\/?([a-zA-Z][a-zA-Z0-9-]*)((?:[^>"']*(?:"[^"]*"|'[^']*'))*[^>"']*)>/g;
 /** Matches an HTML element from its opening tag to the matching closing tag. */
 const HTML_ELEMENT_BLOCK_RE = /<([a-zA-Z][a-zA-Z0-9-]*)[\s>][\s\S]*?<\/\1>/g;
+const NEWLINE_RE = /\n/g;
 /** Matches a newline with surrounding horizontal whitespace. */
 const NEWLINE_WITH_WHITESPACE_RE = /[^\S\n]*\n[^\S\n]*/g;
+/** Matches a run of two or more newlines (a blank line) with surrounding horizontal whitespace. */
+const BLANK_LINE_RE = /[^\S\n]*\n(?:[^\S\n]*\n)+[^\S\n]*/g;
 /** Matches a closing block-level tag followed by non-tag text or by a newline then non-blank content. */
 const CLOSE_BLOCK_TAG_BOUNDARY_RE = /<\/([a-zA-Z][a-zA-Z0-9-]*)>\s*(?:(?!<)(\S)|\n([^\n]))/g;
 /** Strips HTML open/close tags. Used to detect non-tag inner text content. */
@@ -105412,7 +105459,6 @@ const EMPTY_CODE_PLACEHOLDER = {
 
 
 
-
 /**
  * Wraps a node in a "pinned" container if sidebar: true is set.
  */
@@ -105447,16 +105493,13 @@ const textToBlock = (text) => [{ children: textToInline(text), type: 'paragraph'
  */
 const ensureLeadingBreaks = (text) => text.replace(/^\n+/, match => '<br>'.repeat(match.length));
 /** Preprocesses magic block body content before parsing. */
-const preprocessBody = (text) => {
-    return ensureLeadingBreaks(text);
-};
+const preprocessBody = (text, hardBreaks) => (hardBreaks ? ensureLeadingBreaks(text) : text);
 const bodyExtensions = mdxishExtensions(FEATURES.magicBlockBody);
 /** Markdown parser */
 const contentParser = unified()
     .data('micromarkExtensions', bodyExtensions.micromarkExtensions)
     .data('fromMarkdownExtensions', bodyExtensions.fromMarkdownExtensions)
     .use(remarkParse)
-    .use(hard_breaks)
     .use(remarkGfm)
     .use(normalize_malformed_md_syntax);
 /**
@@ -105553,17 +105596,21 @@ const processMarkdownInHtmlString = (html) => {
 /**
  * Separate a closing block-level tag from the content that follows it.
  *
- * Each \n in the original text becomes a <br> tag to preserve spacing, then a
- * blank line (\n\n) is appended so CommonMark ends the HTML block and parses
- * the following content as markdown.
+ * A blank line (\n\n) is appended so CommonMark ends the HTML block and parses the
+ * following content as markdown; with hard breaks each \n also becomes a <br> to keep its spacing.
  */
-const separateBlockTagFromContent = (match, tag, inlineChar, nextLineChar) => {
+const separateBlockTagFromContent = (hardBreaks, match, tag, inlineChar, nextLineChar) => {
     if (!BLOCK_LEVEL_TAGS.has(tag.toLowerCase()))
         return match;
-    const newlineCount = (match.match(/\n/g) ?? []).length;
+    const newlineCount = hardBreaks ? (match.match(NEWLINE_RE) ?? []).length : 0;
     const breaks = '<br>'.repeat(newlineCount);
     return `</${tag}>${breaks}\n\n${inlineChar || nextLineChar}`;
 };
+/**
+ * Newlines inside an HTML block become <br> so CommonMark doesn't end the block on a blank
+ * line. Without hard breaks only blank lines break, but they still have to be replaced.
+ */
+const collapseHtmlBlockNewlines = (html, hardBreaks) => html.replace(hardBreaks ? NEWLINE_WITH_WHITESPACE_RE : BLANK_LINE_RE, '<br>');
 /** Escape a leading (possibly indented) `-`/`*`/`+` so cells don't become bullet lists. */
 const escapeLeadingListMarkers = (text) => text.replace(/^([ \t]*)([-*+])(?=[ \t]|$)/gm, '$1\\$2');
 /**
@@ -105571,15 +105618,13 @@ const escapeLeadingListMarkers = (text) => text.replace(/^([ \t]*)([-*+])(?=[ \t
  * so `<ul><li>_text_</li></ul>` won't convert underscores to emphasis.
  * We parse first, then visit html nodes and process their text content.
  */
-const parseTableCell = (text) => {
+const parseTableCell = (text, hardBreaks) => {
     if (!text.trim())
         return [{ type: 'text', value: '' }];
-    // Convert \n (and surrounding whitespace) to <br> inside HTML blocks so
-    // CommonMark doesn't split them on blank lines.
     const escaped = processBackslashEscapes(text);
     const normalized = escaped
-        .replace(HTML_ELEMENT_BLOCK_RE, match => match.replace(NEWLINE_WITH_WHITESPACE_RE, '<br>'))
-        .replace(CLOSE_BLOCK_TAG_BOUNDARY_RE, separateBlockTagFromContent);
+        .replace(HTML_ELEMENT_BLOCK_RE, match => collapseHtmlBlockNewlines(match, hardBreaks))
+        .replace(CLOSE_BLOCK_TAG_BOUNDARY_RE, (match, tag, inlineChar, nextLineChar) => separateBlockTagFromContent(hardBreaks, match, tag, inlineChar, nextLineChar));
     const processed = escapeLeadingListMarkers(normalized);
     const tree = contentParser.runSync(contentParser.parse(processed));
     // Process markdown inside HTML blocks that have non-tag inner text (e.g. `<div>**x**`
@@ -105628,7 +105673,7 @@ const parseApiHeaderTitle = (text) => {
  * Transform a magicBlock node into final MDAST nodes.
  */
 function transformMagicBlock(blockType, data, rawValue, options = {}) {
-    const { compatibilityMode = false, safeMode = false } = options;
+    const { compatibilityMode = false, hardBreaks = true, safeMode = false } = options;
     // Handle empty data by returning placeholder nodes for known block types
     // This allows the editor to show appropriate placeholder UI instead of nothing
     if (Object.keys(data).length < 1) {
@@ -105767,7 +105812,7 @@ function transformMagicBlock(blockType, data, rawValue, options = {}) {
                 });
             }
             if (hasBody) {
-                const bodyBlocks = parseBlock(preprocessBody(calloutJson.body || ''));
+                const bodyBlocks = parseBlock(preprocessBody(calloutJson.body || '', hardBreaks));
                 children.push(...bodyBlocks);
             }
             const calloutElement = {
@@ -105799,12 +105844,12 @@ function transformMagicBlock(blockType, data, rawValue, options = {}) {
                 mapped[rowIndex][colIndex] = v;
                 return mapped;
             }, []);
-            const tokenizeCell = compatibilityMode
-                ? textToBlock
-                : parseTableCell;
+            const tokenizeCell = compatibilityMode ? textToBlock : (text) => parseTableCell(text, hardBreaks);
             const tableChildren = Array.from({ length: rows + 1 }, (_, y) => ({
                 children: Array.from({ length: cols }, (__, x) => ({
-                    children: sparseData[y]?.[x] ? tokenizeCell(preprocessBody(sparseData[y][x])) : [{ type: 'text', value: '' }],
+                    children: sparseData[y]?.[x]
+                        ? tokenizeCell(preprocessBody(sparseData[y][x], hardBreaks))
+                        : [{ type: 'text', value: '' }],
                     type: y === 0 ? 'tableHead' : 'tableCell',
                 })),
                 type: 'tableRow',
@@ -107641,6 +107686,7 @@ function loadComponents() {
 
 
 
+
 
 
 const defaultTransformers = [
@@ -107679,7 +107725,7 @@ function preprocessContent(content, opts) {
     return processSnakeCaseComponent(result, { knownComponents });
 }
 function mdxishAstProcessor(mdContent, opts = {}) {
-    const { components: userComponents = {}, newEditorTypes = false, safeMode = false, useTailwind } = opts;
+    const { components: userComponents = {}, hardBreaks: enableHardBreaks = true, newEditorTypes = false, safeMode = false, useTailwind, } = opts;
     const components = {
         ...loadComponents(),
         ...userComponents,
@@ -107708,7 +107754,7 @@ function mdxishAstProcessor(mdContent, opts = {}) {
         // The next few transformers must appear after mdxishMdxComponentBlocks
         // so nodes produced by the inline re-parse of component bodies
         // (e.g. code/image/embed inside <Tabs>) get visited too
-        .use(magic_block_transformer)
+        .use(magic_block_transformer, { hardBreaks: enableHardBreaks })
         .use(transform_images, { isMdxish: true })
         .use(defaultTransformers)
         .use(newEditorTypes ? inline_mdx_blocks : undefined) // Merge inline html components (e.g. <Anchor>) into MDAST nodes
@@ -107743,6 +107789,7 @@ function mdxishMdastToMd(mdast) {
         .use(remarkGfm)
         .use(callout_to_jsx)
         .use(mdxish_tables_to_jsx)
+        .use(anchor_to_jsx)
         .use(mdxishCompilers)
         .use(mdxJsxStringify)
         .use(remarkStringify, {
@@ -107764,7 +107811,7 @@ function mdxishMdastToMd(mdast) {
  * @see .claude/context/MDXish/Processor Overview.md
  */
 function mdxish(mdContent, opts = {}) {
-    const { components: userComponents = {}, safeMode = false, variables } = opts;
+    const { components: userComponents = {}, hardBreaks: enableHardBreaks = true, safeMode = false, variables } = opts;
     const components = {
         ...loadComponents(),
         ...userComponents,
@@ -107776,7 +107823,7 @@ function mdxish(mdContent, opts = {}) {
     const { processor, parserReadyContent } = mdxishAstProcessor(contentWithoutComments, opts);
     processor
         .use(safeMode ? undefined : evaluate_exports) // Evaluate `export const/function` and stash scope on file.data.mdxishScope
-        .use(hard_breaks) // Must precede evaluateExpressions to avoid splitting the \n in an evaluated template literal into a <br> node
+        .use(enableHardBreaks ? hard_breaks : undefined) // Must precede evaluateExpressions to avoid splitting the \n in an evaluated template literal into a <br> node
         .use(safeMode ? undefined : evaluate_expressions) // Evaluate self-contained MDX expressions (e.g. `{1+1}`)
         .use(safeMode ? undefined : evaluate_style_block_expressions) // Evaluate `<style>{`...`}</style>` template literals into plain CSS
         .use(variables_code, { variables }) // Resolve <<...>> and {user.*} inside code and inline code nodes
@@ -108764,7 +108811,7 @@ module.exports = /*#__PURE__*/JSON.parse('{"*":["about","acceptCharset","accessK
 /******/ 	// startup
 /******/ 	// Load entry module and return exports
 /******/ 	// This entry module used 'module' so it can't be inlined
-/******/ 	let __webpack_exports__ = __webpack_require__(8071);
+/******/ 	let __webpack_exports__ = __webpack_require__(5168);
 /******/ 	
 /******/ 	return __webpack_exports__;
 /******/ })()