[docs-infra] Allow to persist icons in ToC

[cherniavskii]

• I have followed (at least) the PR section of the contributing guide.

In MUI X, we want to show pricing plan icons in our ToC - see mui/mui-x#9490

Preview: https://deploy-preview-37731--material-ui.netlify.app/experiments/docs/headers

[mui-bot]

Netlify deploy preview

https://deploy-preview-37731--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against ef95c92

[oliviertassinari]

For the history, we added this logic for the support page, e.g. https://mui.com/material-ui/getting-started/support/#blog. I'm not aware of any other places where we do this in the docs.

If we feel that the icons are wrong in the H2, we could also fix it by removing them:

Suggested change

	.replace(
	/([\uE000-\uF8FF]|\uD83C[\uDC00-\uDFFF]|\uD83D[\uDC00-\uDFFF]|[\u2011-\u26FF]|\uD83E[\uDD10-\uDDFF])\uFE0F?/g,
	'',
	) // remove emojis
	.replace(/<\/?[^>]+(>|$)/g, '') // remove HTML

[cherniavskii]

Regarding emojis, I don't have a strong opinion on this - I'm fine with showing them in ToC or removing them from H2 completely.

Regarding HTML, here is an example H2 from MUI X docs:

## Lazy loading [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan)

Which is then converted to HTML:

Lazy loading <a href="/x/introduction/licensing/#pro-plan"><span class="plan-pro"></span></a>

If we keep the HTML above, React throws an error because of the nested <a> tag:

Warning: Prop `dangerouslySetInnerHTML` did not match. Server: "Infinite loading " Client: "Infinite loading <a href=\"/x/introduction/licensing/#pro-plan\"><span class=\"plan-pro\"></span></a>

This is why I ended up keeping the HTML removal logic and adding the icon later if it's included in iconsToPersistInToC. I'm open to a more elegant solution if you have suggestions :)

[oliviertassinari]

React throws an error because of the nested tag:

Ah yes, the mismatch seems to come from the nested <a>, not good, this would fix it:

diff --git a/packages/markdown/parseMarkdown.js b/packages/markdown/parseMarkdown.js
index 3d8f9ddafc..3be9e3d23b 100644
--- a/packages/markdown/parseMarkdown.js
+++ b/packages/markdown/parseMarkdown.js
@@ -238,13 +238,8 @@ function createRender(context) {
         return `<h${level}>${headingHtml}</h${level}>`;
       }

-      const headingText = headingHtml
-        .replace(
-          /([\uE000-\uF8FF]|\uD83C[\uDC00-\uDFFF]|\uD83D[\uDC00-\uDFFF]|[\u2011-\u26FF]|\uD83E[\uDD10-\uDDFF])\uFE0F?/g,
-          '',
-        ) // remove emojis
-        .replace(/<\/?[^>]+(>|$)/g, '') // remove HTML
-        .trim();
+      // Remove links to avoid nested links in the TOCs
+      const headingText = headingHtml.replace(/<a\b[^>]*>/i, '').replace(/<\/a>/i, '');

       // Standardizes the hash from the default location (en) to different locations
       // Need english.md file parsed first

[cherniavskii]

Thanks, this looks better! 🎉

[cherniavskii]

Should we keep <code> tags in ToC?

master	This PR

IMO, it looks slightly better with the <code> tags, especially on this page: https://deploy-preview-37731--material-ui.netlify.app/material-ui/experimental-api/css-theme-variables/usage/

[oliviertassinari]

Fair enough 👍