fetch readme.md as mdx

.gitignore

@@ -12,5 +12,5 @@ package-lock.json
 .cache
 internal-links.tap
 stats.json
-printable.md
+printable.mdx
 repositories/*.json

package.json

@@ -25,7 +25,7 @@
   },
   "scripts": {
     "clean-dist": "rimraf ./dist",
-    "clean-printable": "rimraf src/content/**/printable.md",
+    "clean-printable": "rimraf src/content/**/printable.mdx",
     "preclean": "run-s clean-dist clean-printable",
     "clean": "rimraf src/content/**/_*.md src/**/_*.json repositories/*.json",
     "start": "npm run clean-dist && webpack serve --config webpack.dev.js --env dev --progress --node-env development",

src/components/Site/Site.jsx

@@ -98,7 +98,7 @@ function Site(props) {
       }))
       .filter(
         (page) =>
-          page.title !== 'printable.md' && !page.content.includes('Printable')
+          page.title !== 'printable.mdx' && !page.content.includes('Printable')
       );
   };
 

src/remark-plugins/remark-cleanup-readme/__snapshots__/index.test.js.snap

@@ -0,0 +1,40 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`cleanup readme should clean up div[align="center"] block with paragraph 1`] = `
+"/* @jsxRuntime classic */
+/* @jsx mdx */
+/* @jsxFrag mdx.Fragment */
+const MDXLayout = \\"wrapper\\";
+function MDXContent({components, ...props}) {
+  return <MDXLayout components={components} {...props}><div align=\\"center\\"><p parentName=\\"div\\"><h1 parentName=\\"p\\">{\\"Imagemin Webpack\\"}</h1></p><p parentName=\\"div\\"><p parentName=\\"p\\">{\\"Plugin and Loader for \\"}<a href=\\"http://webpack.js.org/\\" parentName=\\"p\\">{\\"webpack\\"}</a>{\\" to optimize (compress) all images using \\"}<a href=\\"https://github.com/imagemin/imagemin\\" parentName=\\"p\\">{\\"imagemin\\"}</a>{\\".\\\\nDo not worry about size of images, now they are always optimized/compressed.\\"}</p></p></div></MDXLayout>;
+}
+MDXContent.isMDXComponent = true;
+export default MDXContent;
+"
+`;
+
+exports[`cleanup readme should clean up div[align="center"] block without paragraph 1`] = `
+"/* @jsxRuntime classic */
+/* @jsx mdx */
+/* @jsxFrag mdx.Fragment */
+const MDXLayout = \\"wrapper\\";
+function MDXContent({components, ...props}) {
+  return <MDXLayout components={components} {...props}><div align=\\"center\\" /></MDXLayout>;
+}
+MDXContent.isMDXComponent = true;
+export default MDXContent;
+"
+`;
+
+exports[`cleanup readme should clean up nested div[align="center"] block  1`] = `
+"/* @jsxRuntime classic */
+/* @jsx mdx */
+/* @jsxFrag mdx.Fragment */
+const MDXLayout = \\"wrapper\\";
+function MDXContent({components, ...props}) {
+  return <MDXLayout components={components} {...props}><div align=\\"center\\" /></MDXLayout>;
+}
+MDXContent.isMDXComponent = true;
+export default MDXContent;
+"
+`;

src/remark-plugins/remark-cleanup-readme/index.js

@@ -0,0 +1,23 @@
+const visit = require('unist-util-visit');
+// remove items other than paragraphs in div[align="center"]
+// e.g., logo, title and so on.
+// see the original version at https://github.com/webpack/webpack.js.org/blob/webpack-4/src/utilities/process-readme.js#L71
+module.exports = function remarkCleanupReadme() {
+  return function transformer(tree) {
+    visit(tree, 'mdxJsxFlowElement', visitor);
+    function visitor(node) {
+      const alignAttribute = node.attributes.find(
+        (attribute) =>
+          attribute.name === 'align' && attribute.value === 'center'
+      );
+      if (alignAttribute) {
+        const paragraphs = node.children.filter(
+          (child) =>
+            child.type === 'paragraph' ||
+            (child.type === 'mdxJsxFlowElement' && child.name === 'p')
+        );
+        node.children = paragraphs;
+      }
+    }
+  };
+};

src/remark-plugins/remark-cleanup-readme/index.test.js

@@ -0,0 +1,74 @@
+const mdx = require('@mdx-js/mdx');
+describe('cleanup readme', () => {
+  it('should clean up div[align="center"] block without paragraph', () => {
+    const mdxText = `
+<div align="center">
+  <a href="https://github.com/babel/babel">
+    <img src="https://rawgit.com/babel/logo/master/babel.svg" alt="Babel logo" width="200" height="200" />
+  </a>
+  <a href="https://github.com/webpack/webpack">
+    <img src="https://webpack.js.org/assets/icon-square-big.svg" alt="webpack logo" width="200" height="200" />
+  </a>
+</div>
+`;
+    const html = mdx.sync(mdxText, {
+      remarkPlugins: [require('./index.js')],
+    });
+    expect(html).toMatchSnapshot();
+  });
+
+  it('should clean up div[align="center"] block with paragraph', () => {
+    const mdxText = `
+<div align="center">
+  <a href="https://github.com/webpack/webpack">
+    <img width="200" height="200" hspace="10"
+      src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg" />
+  </a>
+  <h1>Imagemin Webpack</h1>
+  <p>
+    Plugin and Loader for <a href="http://webpack.js.org/">webpack</a> to optimize (compress) all images using <a href="https://github.com/imagemin/imagemin">imagemin</a>.
+    Do not worry about size of images, now they are always optimized/compressed.
+  </p>
+</div>
+    `;
+    const html = mdx.sync(mdxText, {
+      remarkPlugins: [require('./index.js')],
+    });
+    expect(html).toMatchSnapshot();
+  });
+
+  it('should clean up nested div[align="center"] block ', () => {
+    // see https://github.com/webpack-contrib/postcss-loader/blob/master/README.md
+    const mdxText = `
+<div align="center">
+  <img
+    width="180"
+    height="180"
+    hspace="10"
+    alt="PostCSS Logo"
+    src="https://api.postcss.org/logo.svg" />
+  <a href="https://github.com/webpack/webpack">
+    <img
+      width="200"
+      height="200"
+      hspace="10"
+      src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg" />
+  </a>
+  <div align="center">
+    <a href="https://evilmartians.com/?utm_source=postcss">
+      <img
+        src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
+        alt="Sponsored by Evil Martians"
+        width="236"
+        height="54"
+        vspace="10" />
+    </a>
+  </div>
+</div>
+        `;
+    const html = mdx.sync(mdxText, {
+      remarkPlugins: [require('./index.js')],
+    });
+    expect(html).toMatchSnapshot();
+  });
+});

src/scripts/concatenate-docs.js

@@ -5,16 +5,16 @@ const front = require('front-matter');
 
 // root path
 const rootPath = path.join('src', 'content');
-const outFileName = 'printable.md';
+const outFileName = 'printable.mdx';
 
 console.info(
-  'Concatenating *.md files of each content directory to create chapter-wide help files to be used for printing'
+  'Concatenating *.mdx files of each content directory to create chapter-wide help files to be used for printing'
 );
 
 // getDirectoryRecursive() recursively walks through all sub directories of the provided path
-// concatenates the .md files content in each directory, sorted by their FrontMatter sort
-// attribute, and creates a compound MarkDown file named by using the directory name,
-// prefixed by an underscore and suffixed by '_all.md' from the concatenated content
+// concatenates the .mdx files content in each directory, sorted by their FrontMatter sort
+// attribute, and creates a compound mdx file named by using the directory name,
+// prefixed by an underscore and suffixed by '_all.mdx' from the concatenated content
 // in the corresponding directory.
 function getDirectoryRecursive(basePath) {
   console.log(`Processing: ${basePath}`);
@@ -34,14 +34,26 @@ function getDirectoryRecursive(basePath) {
       // if the directory entry is a directory, recurse into that directory
       if (fs.statSync(fullPath).isDirectory()) {
         getDirectoryRecursive(fullPath);
-      } else if (fullPath.endsWith('.md') || fullPath.endsWith('.mdx')) {
-        fileContents[fileContents.length] = front(
-          fs.readFileSync(fullPath).toString()
-        );
+      } else if (fullPath.endsWith('.mdx')) {
+        // import the respective mdx file
+        // prefix a `W` to prevent filename like 12345.mdx
+        const basename = path
+          .basename(file, '.mdx')
+          .split('-')
+          .map((x) => x.toUpperCase())
+          .join('');
+        fileContents[fileContents.length] = {
+          ...front(fs.readFileSync(fullPath).toString()),
+          body: `
+import W${basename} from './${file}'
+
+<W${basename} />
+`,
+        };
       }
     }
 
-    // sort MarkDown files by FrontMatter 'sort' attribute (QuickSort)
+    // sort mdx files by FrontMatter 'sort' attribute (QuickSort)
     for (let i = 0; i < fileContents.length - 1; ++i)
       for (let j = i + 1; j < fileContents.length; ++j) {
         const left = fileContents[i].attributes;
@@ -73,7 +85,6 @@ contributors:
     targetFile.on('error', (error) => {
       throw error;
     });
-
     for (let file of fileContents) {
       // use FrontMatter 'title' attribute as main heading of target file
       targetFile.write(os.EOL + os.EOL + '# ' + file.attributes.title + os.EOL);

src/utilities/fetch-package-readmes.js

@@ -34,7 +34,7 @@ async function main() {
       const url = `https://raw.githubusercontent.com/${repo}/master/README.md`;
       const htmlUrl = `https://github.com/${repo}`;
       const editUrl = `${htmlUrl}/edit/master/README.md`;
-      const fileName = path.resolve(outputDir, `_${packageName}.md`);
+      const fileName = path.resolve(outputDir, `_${packageName}.mdx`);
 
       let title = packageName;
 

src/utilities/process-readme.js

@@ -92,12 +92,11 @@ function getMatches(string, regex) {
 
 module.exports = function processREADME(body, options = {}) {
   let processingString = body
-    // remove items other than paragraphs in div[align="center"]
-    // e.g., logo, title and so on.
-    .replace(/[^]*?<div align="center">([^]*?)<\/div>/, (match, content) => {
-      let parsed = content.match(/<p>\s+([^]*?)\s+<\/?p>/);
-      return parsed ? parsed[1] : '';
-    })
+    // close <img> tags
+    .replace(
+      /<(img\s[^>]*?src\s*=\s*['"][^'"]*?['"][^>/]*?)>(?![^<]*<\/img)/g,
+      '<$1/>'
+    )
     // Replace lone h1 formats
     .replace(/<h1.*?>.+?<\/h1>/, '')
     .replace(/^# .+/m, '')

src/utilities/process-readme.test.js

@@ -28,35 +28,4 @@ describe('processReadme', () => {
       '- [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)'
     );
   });
-
-  it('should clean up div[align="center"] block with paragraph', () => {
-    const loaderMDData = `
-<div align="center">
-  <a href="https://github.com/webpack/webpack">
-    <img width="200" height="200" hspace="10"
-      src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg">
-  </a>
-  <h1>Imagemin Webpack</h1>
-  <p>
-    Plugin and Loader for <a href="http://webpack.js.org/">webpack</a> to optimize (compress) all images using <a href="https://github.com/imagemin/imagemin">imagemin</a>.
-    Do not worry about size of images, now they are always optimized/compressed.
-  </p>
-</div>`;
-    expect(processReadme(loaderMDData))
-      .toEqual(`Plugin and Loader for <a href="http://webpack.js.org/">webpack</a> to optimize (compress) all images using <a href="https://github.com/imagemin/imagemin">imagemin</a>.
-    Do not worry about size of images, now they are always optimized/compressed.`);
-  });
-
-  it('should clean up div[align="center"] block without paragraph', () => {
-    const loaderMDData = `
-<div align="center">
-  <a href="https://github.com/babel/babel">
-    <img src="https://rawgit.com/babel/logo/master/babel.svg" alt="Babel logo" width="200" height="200">
-  </a>
-  <a href="https://github.com/webpack/webpack">
-    <img src="https://webpack.js.org/assets/icon-square-big.svg" alt="webpack logo" width="200" height="200">
-  </a>
-</div>`;
-    expect(processReadme(loaderMDData)).toEqual('');
-  });
 });

webpack.common.js

@@ -8,6 +8,7 @@ const mdPlugins = [
   require('remark-slug'),
   remarkResponsiveTable,
   require('remark-emoji'),
+  require('./src/remark-plugins/remark-cleanup-readme/index.js'),
   [
     require('./src/remark-plugins/remark-custom-asides/index.js'),
     {