fix: migrating escaped html

__tests__/lib/mdast/html-blocks/in.mdx

@@ -0,0 +1,7 @@
+<HTMLBlock>{`
+<pre>
+  <code>
+    RegexpExtract([Address], "\\\\s*([a-zA-Z]+)", 2)
+  </code>
+</pre>
+`}</HTMLBlock>

__tests__/lib/mdast/html-blocks/out.json

@@ -0,0 +1,20 @@
+{
+  "children": [
+    {
+      "children": [
+        {
+          "type": "text",
+          "value": "<pre>\n  <code>\n    RegexpExtract([Address], \"\\\\\\\\s*([a-zA-Z]+)\", 2)\n  </code>\n</pre>"
+        }
+      ],
+      "data": {
+        "hName": "html-block",
+        "hProperties": {
+          "html": "<pre>\n  <code>\n    RegexpExtract([Address], \"\\\\\\\\s*([a-zA-Z]+)\", 2)\n  </code>\n</pre>"
+        }
+      },
+      "type": "html-block"
+    }
+  ],
+  "type": "root"
+}

__tests__/lib/mdast/index.test.ts

@@ -5,6 +5,8 @@ import esmMdx from './esm/in.mdx?raw';
 // @ts-expect-error - these are being imported as json
 import esmJson from './esm/out.json';
 // @ts-expect-error - these are being imported as strings
+import htmlBlockMdx from './html-blocks/in.mdx?raw';
+import htmlBlockJson from './html-blocks/out.json';
 import inlineImagesMdx from './images/inline/in.mdx?raw';
 // @ts-expect-error - these are being imported as json
 import inlineImagesJson from './images/inline/out.json';
@@ -18,11 +20,8 @@ import tablesMdx from './tables/in.mdx?raw';
 import tablesJson from './tables/out.json';
 // @ts-expect-error - these are being imported as strings
 import variablesMdx from './variables/in.mdx?raw';
-// @ts-expect-error - these are being imported as json
 import variablesJson from './variables/out.json';
-// @ts-expect-error - these are being imported as strings
 import variablesWithSpacesMdx from './variables-with-spaces/in.mdx?raw';
-// @ts-expect-error - these are being imported as json
 import variablesWithSpacesJson from './variables-with-spaces/out.json';
 
 describe('mdast transformer', () => {
@@ -62,6 +61,12 @@ describe('mdast transformer', () => {
     expect(mdast(esmMdx)).toStrictEqualExceptPosition(esmJson);
   });
 
+  it('parses HTMLBlock contents', () => {
+    // @ts-expect-error - the custom matcher types are not being set up
+    // correctly
+    expect(mdast(htmlBlockMdx)).toStrictEqualExceptPosition(htmlBlockJson);
+  });
+
   it('throws an error when a component does not exist and missingComponents === "throw"', () => {
     const mdx = '<NonExistentComponent />';
 

__tests__/migration/html-blocks/fixtures/html-block-escapes-newlines/in.md

@@ -0,0 +1,5 @@
+[block:html]
+{
+  "html": "<pre>\n  <code> \n    RegexpExtract([Address], \"\\\\s*([a-zA-Z]+)\", 2)\n  </code>\n</pre>"
+}
+[/block]

__tests__/migration/html-blocks/fixtures/html-block-escapes-newlines/out.mdx

@@ -0,0 +1,7 @@
+<HTMLBlock>{`
+<pre>
+  <code> 
+    RegexpExtract([Address], "\\\\s*([a-zA-Z]+)", 2)
+  </code>
+</pre>
+`}</HTMLBlock>

__tests__/migration/html-blocks/fixtures/html-block-escapes/in.md

@@ -0,0 +1,5 @@
+[block:html]
+{
+"html": "<pre><code>RegexpExtract([Address], \"\\\\s*([a-zA-Z]+)\", 2)</code></pre>"
+}
+[/block]

__tests__/migration/html-blocks/fixtures/html-block-escapes/out.mdx

@@ -0,0 +1,3 @@
+<HTMLBlock>{`
+<pre><code>RegexpExtract([Address], "\\\\s*([a-zA-Z]+)", 2)</code></pre>
+`}</HTMLBlock>

__tests__/migration/html-blocks/fixtures/html-block-with-brackets/in.md

@@ -0,0 +1,5 @@
+[block:html]
+{
+  "html": "{`\n<pre>\n  <code>\n    RegexpExtract([Address], \"\\\\s*([a-zA-Z]+)\", 2)\n  </code>\n</pre>\n`}"
+}
+[/block]

__tests__/migration/html-blocks/fixtures/html-block-with-brackets/out.mdx

@@ -0,0 +1,9 @@
+<HTMLBlock>{`
+{\`
+<pre>
+  <code>
+    RegexpExtract([Address], "\\\\s*([a-zA-Z]+)", 2)
+  </code>
+</pre>
+\`}
+`}</HTMLBlock>

__tests__/migration/html-blocks/index.test.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+
+import { migrate } from '../../helpers';
+
+describe('migrating html blocks', () => {
+  it('correctly escapes back ticks', () => {
+    const md = `
+[block:html]
+{
+  "html": "<a href=\\"example.com\\">\`example.com\`</a>"
+}
+[/block]
+`;
+
+    const mdx = migrate(md);
+    expect(mdx).toMatchInlineSnapshot(`
+      "<HTMLBlock>{\`
+      <a href="example.com">\\\`example.com\\\`</a>
+      \`}</HTMLBlock>
+      "
+    `);
+  });
+
+  it('does not escape already escaped backticks', () => {
+    const md = `
+[block:html]
+{
+  "html": "<a href=\\"example.com\\">${'\\\\`example.com\\\\`'}</a>"
+}
+[/block]
+`;
+
+    const mdx = migrate(md);
+    expect(mdx).toMatchInlineSnapshot(`
+      "<HTMLBlock>{\`
+      <a href="example.com">\\\\\`example.com\\\\\`</a>
+      \`}</HTMLBlock>
+      "
+    `);
+  });
+
+  it('does not unescape backslashes', async () => {
+    const md = fs.readFileSync(`${__dirname}/fixtures/html-block-escapes/in.md`, 'utf-8');
+
+    await expect(migrate(md)).toMatchFileSnapshot(`${__dirname}/fixtures/html-block-escapes/out.mdx`);
+  });
+
+  it('correctly migrates html with newlines', async () => {
+    const md = fs.readFileSync(`${__dirname}/fixtures/html-block-escapes-newlines/in.md`, 'utf-8');
+
+    await expect(migrate(md)).toMatchFileSnapshot(`${__dirname}/fixtures/html-block-escapes-newlines/out.mdx`);
+  });
+
+  it('correctly migrates html with brackets and template literals', async () => {
+    const md = fs.readFileSync(`${__dirname}/fixtures/html-block-with-brackets/in.md`, 'utf-8');
+
+    await expect(migrate(md)).toMatchFileSnapshot(`${__dirname}/fixtures/html-block-with-brackets/out.mdx`);
+  });
+});

lib/migrate.ts

@@ -1,4 +1,5 @@
 import migrateCallouts from '../processor/transform/migrate-callouts';
+import migrateHtmlBlocks from '../processor/transform/migrate-html-blocks';
 import migrateHtmlTags from '../processor/transform/migrate-html-tags';
 import migrateLinkReferences from '../processor/transform/migrate-link-references';
 
@@ -9,12 +10,17 @@ import migrateComments from './utils/migrateComments';
 const migrateDoc = (doc: string, { rdmd }): string => {
   const ast = mdastV6(doc, { rdmd });
 
-  return mdx(ast, { remarkTransformers: [migrateCallouts, [migrateLinkReferences, { rdmd }], migrateHtmlTags], file: doc })
-    .replaceAll(/ /g, ' ')
-    // @note: I'm not sure what's happening, but I think mdx is converting an
-    // 'a' to 'a' as a means of escaping it. I think this helps with
-    // parsing weird cases.
-    .replaceAll(/a/g, 'a');
+  return (
+    mdx(ast, {
+      remarkTransformers: [migrateCallouts, [migrateLinkReferences, { rdmd }], migrateHtmlTags, migrateHtmlBlocks],
+      file: doc,
+    })
+      .replaceAll(/ /g, ' ')
+      // @note: I'm not sure what's happening, but I think mdx is converting an
+      // 'a' to 'a' as a means of escaping it. I think this helps with
+      // parsing weird cases.
+      .replaceAll(/a/g, 'a')
+  );
 };
 
 const migrate = (doc: string, opts): string => {

processor/transform/migrate-html-blocks.ts

@@ -0,0 +1,20 @@
+import type { Transform } from 'mdast-util-from-markdown';
+import type { HTMLBlock } from 'types';
+
+import { visit } from 'unist-util-visit';
+
+const MigrateHtmlBlocks = (): Transform => tree => {
+  visit(tree, 'html-block', (node: HTMLBlock) => {
+    const { html, runScripts } = node.data?.hProperties || {};
+    const escaped = html.replaceAll(/\\/g, '\\\\');
+
+    node.data.hProperties = {
+      ...(runScripts && { runScripts }),
+      html: escaped,
+    };
+  });
+
+  return tree;
+};
+
+export default MigrateHtmlBlocks;

processor/transform/readme-to-mdx.ts

@@ -77,7 +77,6 @@ const readmeToMdx = (): Transform => tree => {
 
   visit(tree, 'figure', (figure, index, parent) => {
     const [image, caption] = figure.children;
-
     const { align, width } = image.data.hProperties;
     const border = image.data.hProperties.className === 'border';