fix: fix rendering content in table magic blocks by maximilianfalco · Pull Request #1318 · readmeio/markdown

maximilianfalco · 2026-02-03T04:39:27Z

	Fix CX-2870	Fix CX-2830	Fix CX-2872	Fix CX-2869

🧰 Changes

Add preprocessing in parseTableCell of magic-block-transformer to:

Process backslash escapes (\< → <) and col characters (|)
Escape invalid HTML tags
Convert markdown emphasis/strong/code to HTML inside HTML blocks
Normalize whitespace to prevent raw HTML block mode

🧬 QA & Testing

- also created the appropriate transformer - deleted the old `mdxish-magic-blocks` transformer

- this was necessary since the old logic introduced whitespaces that are no longer here

…o/mdxish-magic-blocks-in-lists

… add tests

…o/mdxish-magic-blocks-in-lists

- fixed issue where callouts without title werent rendering properly - fixed issue where callouts without body werent rendering properly - fixed issue where caption of images would be rendered as plain text instead of being parsed

- added tests as well

…o/mdxish-magic-blocks-in-lists

- malformed syntax is returned as raw text instead of erroring

maximilianfalco · 2026-02-05T12:47:34Z

@rafegoldberg I did a bit of refactor on this, its a bit more convoluted and complex but it should be more robust in general. it might degrade performance a tiny bit 🤞 but it shouldnt really matter since we rarely see these complex magic block tables anyways...

ive placed all the refactor here 249d6bd. these are the steps now

still preprocess escaped syntax. i dont see any other way around this since we need to transform them into safe HTML strings
we parse the markdown as usual (markdown -> MDAST)

when we hit an html node, we store the entire value as text. including the markdown within

we find all html nodes and run processMarkdownInHtmlString() on them (if we find there is markdown syntax). inside this a few things happen:
we convert the html string to HAST
the HAST has text nodes that contain these markdown syntaxes. we find these nodes and parse them from text -> HAST
we are then left with a single unified HAST tree, containing the original HAST components and the parse markdown syntaxes
we then stringify (HAST -> text) the entire tree so that the original html node in step 2 still maintains a regular HTML node that contains HTML string

its a bit confusing yea... took my head a bit too to get around it but it looks to be the most robust way... we still needed to re-stringify it so that we maintain the original html node and its contents in the MDAST tree

I asked claude to help visualize a test case and it did it pretty well here:

Detailed Flow

Input: "<ul><li>**bold**</li></ul>"

---
Step 1: Escape backslashes

Input:  "<ul><li>**bold**</li></ul>"
Output: "<ul><li>**bold**</li></ul>"  (unchanged, no backslashes)

Example with backslashes:
Input:  "yes\|no"
Output: "yes|no"

---
Step 2: Parse markdown → MDAST

contentParser.parse("<ul><li>**bold**</li></ul>")

┌─────────────────────────────────────────────────────────┐
│ MDAST                                                   │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "html",                                     │
│       value: "<ul><li>**bold**</li></ul>"  ← PROBLEM!   │
│     }                                        still text │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘

Why this happens: CommonMark spec says HTML blocks are opaque.
The parser doesn't look inside.

---
Step 3: processMarkdownInHtmlNodes(tree)

Visits each html node and calls processMarkdownInHtmlString(node.value)

---
Step 3a: Parse HTML string → HAST

htmlToHast.parse("<ul><li>**bold**</li></ul>")

┌─────────────────────────────────────────────────────────┐
│ HAST                                                    │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "element",                                  │
│       tagName: "ul",                                    │
│       children: [                                       │
│         {                                               │
│           type: "element",                              │
│           tagName: "li",                                │
│           children: [                                   │
│             {                                           │
│               type: "text",                             │
│               value: "**bold**"  ← markdown still here! │
│             }                                           │
│           ]                                             │
│         }                                               │
│       ]                                                 │
│     }                                                   │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘

---
Step 3b: Find text nodes, parse as markdown → HAST

For each text node "**bold**":

markdownToHast.parse("**bold**")

┌─────────────────────────────────────────────────────────┐
│ Intermediate MDAST (from markdown parser)               │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "paragraph",                                │
│       children: [                                       │
│         {                                               │
│           type: "strong",                               │
│           children: [                                   │
│             { type: "text", value: "bold" }             │
│           ]                                             │
│         }                                               │
│       ]                                                 │
│     }                                                   │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼ remarkRehype
┌─────────────────────────────────────────────────────────┐
│ Converted to HAST                                       │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "element",                                  │
│       tagName: "p",          ← unwrap this!             │
│       children: [                                       │
│         {                                               │
│           type: "element",                              │
│           tagName: "strong",                            │
│           children: [                                   │
│             { type: "text", value: "bold" }             │
│           ]                                             │
│         }                                               │
│       ]                                                 │
│     }                                                   │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼ unwrap <p>
┌─────────────────────────────────────────────────────────┐
│ Final HAST nodes to insert                              │
├─────────────────────────────────────────────────────────┤
│ [                                                       │
│   {                                                     │
│     type: "element",                                    │
│     tagName: "strong",                                  │
│     children: [                                         │
│       { type: "text", value: "bold" }                   │
│     ]                                                   │
│   }                                                     │
│ ]                                                       │
└─────────────────────────────────────────────────────────┘

---
Step 3c: Replace text node in HAST

┌─────────────────────────────────────────────────────────┐
│ HAST (after replacement)                                │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "element",                                  │
│       tagName: "ul",                                    │
│       children: [                                       │
│         {                                               │
│           type: "element",                              │
│           tagName: "li",                                │
│           children: [                                   │
│             {                                           │
│               type: "element",                          │
│               tagName: "strong",  ← was text "**bold**" │
│               children: [                               │
│                 { type: "text", value: "bold" }         │
│               ]                                         │
│             }                                           │
│           ]                                             │
│         }                                               │
│       ]                                                 │
│     }                                                   │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘

---
Step 3d: Stringify HAST → HTML string

hastToHtml.stringify(hast)

Output: "<ul><li><strong>bold</strong></li></ul>"

---
Step 3e: Update MDAST html node

┌─────────────────────────────────────────────────────────┐
│ MDAST (after processMarkdownInHtmlNodes)                │
├─────────────────────────────────────────────────────────┤
│ {                                                       │
│   type: "root",                                         │
│   children: [                                           │
│     {                                                   │
│       type: "html",                                     │
│       value: "<ul><li><strong>bold</strong></li></ul>"  │
│     }                        ↑ markdown now converted!  │
│   ]                                                     │
│ }                                                       │
└─────────────────────────────────────────────────────────┘

---
Step 4: Unwrap and return

return tree.children.flatMap(n =>
  n.type === 'paragraph' ? n.children : [n]
);

Since it's an html node (not paragraph), return as-is:

┌─────────────────────────────────────────────────────────┐
│ Final Output: MdastNode[]                               │
├─────────────────────────────────────────────────────────┤
│ [                                                       │
│   {                                                     │
│     type: "html",                                       │
│     value: "<ul><li><strong>bold</strong></li></ul>"    │
│   }                                                     │
│ ]                                                       │
└─────────────────────────────────────────────────────────┘

…o/fix-rendering-content-in-table-magic-blocks

eaglethrost · 2026-02-10T07:15:31Z

Code looks good to me. Yeah it's not ideal we have to create another mini md processor just for magic blocks, but I think works for now. We didn't design the table magic block to convert to the MDX

because technically they're a different and might have different stylings and behaviour. But in the future I do think it's worth doing so to reduce code duplications like this and clean it up further

rafegoldberg

Appreciate the details @maximilianfalco. I'm (very) cautiously approving this, though I'd love to address the following comments ASAP.