[docs-infra] Add a feature list "component" (#41484)

Co-authored-by: alexandre <[email protected]>

docs/data/docs-infra/pages.ts

@@ -14,6 +14,7 @@ const pages: readonly MuiPage[] = [
     children: [
       { pathname: '/experiments/docs/callouts' },
       { pathname: '/experiments/docs/codeblock' },
+      { pathname: '/experiments/docs/custom-components' },
       { pathname: '/experiments/docs/demos' },
       { pathname: '/experiments/docs/data-grid-premium', title: 'API DataGridPremium' },
     ],

docs/pages/experiments/docs/custom-components.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from './custom-components.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}

docs/pages/experiments/docs/custom-components.md

@@ -0,0 +1,19 @@
+# Custom components
+
+<p class="description">They're either custom markdown components or passed through directly via "components".</p>
+
+## Header chips
+
+{{"component": "modules/components/ComponentLinkHeader.js"}}
+
+## Feature list
+
+Available through the custom `<featureList>` tag.
+
+<featureList>
+- Manages modal stacking when one-at-a-time just isn't enough.
+- Creates a backdrop, for disabling interaction below the modal.est
+- It disables scrolling of the page content while open.
+- It properly manages focus; moving to the modal content, and keeping it there until the modal is closed.
+- Adds the appropriate ARIA roles automatically.
+</featureList>

docs/src/modules/components/MarkdownElement.js

@@ -609,6 +609,21 @@ const Root = styled('div')(
         marginBottom: theme.spacing(1),
       },
     },
+    '& .feature-list': {
+      padding: 0,
+      listStyle: 'none',
+      '& li': {
+        marginBottom: 6,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 12,
+        '::before': {
+          content: `url('/static/branding/pricing/yes-light.svg')`,
+          width: '18px',
+          height: '18px',
+        },
+      },
+    },
     '& .MuiCode-title': {
       padding: theme.spacing(1.5),
       display: 'flex',
@@ -777,6 +792,13 @@ const Root = styled('div')(
           backgroundColor: `var(--muidocs-palette-primaryDark-800, ${darkTheme.palette.primaryDark[800]})`,
         },
       },
+      '& .feature-list': {
+        '& li': {
+          '::before': {
+            content: `url('/static/branding/pricing/yes-dark.svg')`,
+          },
+        },
+      },
     },
   }),
 );

packages/markdown/parseMarkdown.js

@@ -188,6 +188,7 @@ function getContents(markdown) {
     .replace(headerRegExp, '') // Remove header information
     .split(/^{{("(?:demo|component)":.*)}}$/gm) // Split markdown into an array, separating demos
     .flatMap((text) => text.split(/^(<codeblock.*?<\/codeblock>)$/gmsu))
+    .flatMap((text) => text.split(/^(<featureList.*?<\/featureList>)$/gmsu))
     .filter((content) => !emptyRegExp.test(content)); // Remove empty lines
   return rep;
 }
@@ -212,23 +213,37 @@ function getDescription(markdown) {
 }
 
 function getCodeblock(content) {
-  if (content.startsWith('<codeblock')) {
-    const storageKey = content.match(/^<codeblock [^>]*storageKey=["|'](\S*)["|'].*>/m)?.[1];
-    const blocks = [...content.matchAll(/^```(\S*) (\S*)\n(.*?)\n```/gmsu)].map(
-      ([, language, tab, code]) => ({ language, tab, code }),
-    );
-
-    const blocksData = blocks.filter(
-      (block) => block.tab !== undefined && !emptyRegExp.test(block.code),
-    );
+  if (!content.startsWith('<codeblock')) {
+    return undefined;
+  }
+  const storageKey = content.match(/^<codeblock [^>]*storageKey=["|'](\S*)["|'].*>/m)?.[1];
+  const blocks = [...content.matchAll(/^```(\S*) (\S*)\n(.*?)\n```/gmsu)].map(
+    ([, language, tab, code]) => ({ language, tab, code }),
+  );
+
+  const blocksData = blocks.filter(
+    (block) => block.tab !== undefined && !emptyRegExp.test(block.code),
+  );
+
+  return {
+    type: 'codeblock',
+    data: blocksData,
+    storageKey,
+  };
+}
 
-    return {
-      type: 'codeblock',
-      data: blocksData,
-      storageKey,
-    };
+function getFeatureList(content) {
+  if (!content.startsWith('<featureList')) {
+    return undefined;
   }
-  return undefined;
+  const lines = content
+    .split('\n')
+    .filter((line) => line.startsWith('- '))
+    .map((line) => line.slice(2));
+
+  return ['<ul class="feature-list">', ...lines.map((line) => `<li>${line}</li>`), '</ul>'].join(
+    '',
+  );
 }
 
 /**
@@ -476,6 +491,7 @@ module.exports = {
   getContents,
   getDescription,
   getCodeblock,
+  getFeatureList,
   getHeaders,
   getTitle,
   renderMarkdown,

packages/markdown/prepareMarkdown.js

@@ -7,6 +7,7 @@ const {
   getContents,
   getDescription,
   getCodeblock,
+  getFeatureList,
   getHeaders,
   getTitle,
 } = require('./parseMarkdown');
@@ -155,13 +156,18 @@ ${headers.hooks
             return null;
           }
         }
-
         const codeblock = getCodeblock(content);
 
         if (codeblock) {
           return codeblock;
         }
 
+        const featureList = getFeatureList(content);
+
+        if (featureList) {
+          return featureList;
+        }
+
         return render(content);
       });