@docusaurus/mdx-loader 2.0.0-beta.0f144213d → 2.0.0-beta.11

package/src/remark/headings/{index.js → index.ts}

@@ -7,29 +7,33 @@
 
 /* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
 
-const {parseMarkdownHeadingId} = require('@docusaurus/utils');
-const visit = require('unist-util-visit');
-const toString = require('mdast-util-to-string');
-const slugs = require('github-slugger')();
+import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
+import visit, {Visitor} from 'unist-util-visit';
+import toString from 'mdast-util-to-string';
+import type {Transformer} from 'unified';
+import type {Parent} from 'unist';
+import type {Heading, Text} from 'mdast';
 
-function headings() {
-  const transformer = (ast) => {
-    slugs.reset();
+function headings(): Transformer {
+  const transformer: Transformer = (ast) => {
+    const slugs = createSlugger();
 
-    function visitor(headingNode) {
-      const data = headingNode.data || (headingNode.data = {}); // eslint-disable-line
-      const properties = data.hProperties || (data.hProperties = {});
+    const visitor: Visitor<Heading> = (headingNode) => {
+      const data = headingNode.data || (headingNode.data = {});
+      const properties = (data.hProperties || (data.hProperties = {})) as {
+        id: string;
+      };
       let {id} = properties;
 
       if (id) {
-        id = slugs.slug(id, true);
+        id = slugs.slug(id, {maintainCase: true});
       } else {
         const headingTextNodes = headingNode.children.filter(
           ({type}) => !['html', 'jsx'].includes(type),
         );
         const heading = toString(
           headingTextNodes.length > 0
-            ? {children: headingTextNodes}
+            ? ({children: headingTextNodes} as Parent)
             : headingNode,
         );
 
@@ -42,8 +46,9 @@ function headings() {
           // When there's an id, it is always in the last child node
           // Sometimes heading is in multiple "parts" (** syntax creates a child node):
           // ## part1 *part2* part3 {#id}
-          const lastNode =
-            headingNode.children[headingNode.children.length - 1];
+          const lastNode = headingNode.children[
+            headingNode.children.length - 1
+          ] as Text;
 
           if (headingNode.children.length > 1) {
             const lastNodeText = parseMarkdownHeadingId(lastNode.value).text;
@@ -63,7 +68,7 @@ function headings() {
 
       data.id = id;
       properties.id = id;
-    }
+    };
 
     visit(ast, 'heading', visitor);
   };
@@ -71,4 +76,4 @@ function headings() {
   return transformer;
 }
 
-module.exports = headings;
+export default headings;

package/src/remark/toc/__tests__/__snapshots__/{index.test.js.snap → index.test.ts.snap}

@@ -9,24 +9,29 @@ exports[`inline code should be escaped 1`] = `
 			{
 				value: '<code>&lt;Head&gt;Test&lt;/Head&gt;</code>',
 				id: 'headtesthead',
-				children: []
+				children: [],
+				level: 3
 			}
-		]
+		],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div /&gt;</code>',
 		id: 'div-',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div&gt; Test &lt;/div&gt;</code>',
 		id: 'div-test-div',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>&lt;div&gt;&lt;i&gt;Test&lt;/i&gt;&lt;/div&gt;</code>',
 		id: 'divitestidiv',
-		children: []
+		children: [],
+		level: 2
 	}
 ];
 
@@ -51,24 +56,29 @@ exports[`non text phrasing content 1`] = `
 			{
 				value: '<strong>Importance</strong>',
 				id: 'importance',
-				children: []
+				children: [],
+				level: 3
 			}
-		]
+		],
+		level: 2
 	},
 	{
 		value: '<del>Strikethrough</del>',
 		id: 'strikethrough',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<i>HTML</i>',
 		id: 'html',
-		children: []
+		children: [],
+		level: 2
 	},
 	{
 		value: '<code>inline.code()</code>',
 		id: 'inlinecode',
-		children: []
+		children: [],
+		level: 2
 	}
 ];
 

package/src/remark/toc/__tests__/{index.test.js → index.test.ts}

@@ -12,7 +12,7 @@ import vfile from 'to-vfile';
 import plugin from '../index';
 import headings from '../../headings/index';
 
-const processFixture = async (name, options) => {
+const processFixture = async (name, options?) => {
   const path = join(__dirname, 'fixtures', `${name}.md`);
   const file = await vfile.read(path);
   const result = await remark()
@@ -41,7 +41,8 @@ test('text content', async () => {
     	{
     		value: 'Endi',
     		id: 'endi',
-    		children: []
+    		children: [],
+    		level: 3
     	},
     	{
     		value: 'Endi',
@@ -50,14 +51,17 @@ test('text content', async () => {
     			{
     				value: 'Yangshun',
     				id: 'yangshun',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	},
     	{
     		value: 'I ♥ unicode.',
     		id: 'i--unicode',
-    		children: []
+    		children: [],
+    		level: 2
     	}
     ];
 
@@ -87,7 +91,8 @@ test('should export even with existing name', async () => {
     	{
     		value: 'Thanos',
     		id: 'thanos',
-    		children: []
+    		children: [],
+    		level: 2
     	},
     	{
     		value: 'Tony Stark',
@@ -96,9 +101,11 @@ test('should export even with existing name', async () => {
     			{
     				value: 'Avengers',
     				id: 'avengers',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	}
     ];
 
@@ -121,7 +128,8 @@ test('should export with custom name', async () => {
     	{
     		value: 'Endi',
     		id: 'endi',
-    		children: []
+    		children: [],
+    		level: 3
     	},
     	{
     		value: 'Endi',
@@ -130,14 +138,17 @@ test('should export with custom name', async () => {
     			{
     				value: 'Yangshun',
     				id: 'yangshun',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	},
     	{
     		value: 'I ♥ unicode.',
     		id: 'i--unicode',
-    		children: []
+    		children: [],
+    		level: 2
     	}
     ];
 
@@ -171,7 +182,8 @@ test('should insert below imports', async () => {
     	{
     		value: 'Title',
     		id: 'title',
-    		children: []
+    		children: [],
+    		level: 2
     	},
     	{
     		value: 'Test',
@@ -180,9 +192,11 @@ test('should insert below imports', async () => {
     			{
     				value: 'Again',
     				id: 'again',
-    				children: []
+    				children: [],
+    				level: 3
     			}
-    		]
+    		],
+    		level: 2
     	}
     ];
 

package/src/remark/toc/__tests__/search.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import remark from 'remark';
+import mdx from 'remark-mdx';
+import search from '../search';
+import headings from '../../headings/index';
+
+const getHeadings = async (mdText: string) => {
+  const node = remark().parse(mdText);
+  const result = await remark().use(headings).use(mdx).run(node);
+  return search(result);
+};
+
+test('should process all heading levels', async () => {
+  const md = `
+# Alpha
+
+## Bravo
+
+### Charlie
+
+#### Delta
+
+##### Echo
+
+###### Foxtrot
+
+  `;
+
+  expect(await getHeadings(md)).toEqual([
+    {
+      children: [
+        {
+          children: [
+            {
+              children: [
+                {
+                  children: [
+                    {
+                      children: [],
+                      id: 'foxtrot',
+                      level: 6,
+                      value: 'Foxtrot',
+                    },
+                  ],
+                  id: 'echo',
+                  level: 5,
+                  value: 'Echo',
+                },
+              ],
+              id: 'delta',
+              level: 4,
+              value: 'Delta',
+            },
+          ],
+          id: 'charlie',
+          level: 3,
+          value: 'Charlie',
+        },
+      ],
+      id: 'bravo',
+      level: 2,
+      value: 'Bravo',
+    },
+  ]);
+});
+
+test('should process real-world well-formatted md', async () => {
+  const md = `
+# title
+
+some text
+
+## section 1
+
+some text
+
+### subsection 1-1
+
+some text
+
+#### subsection 1-1-1
+
+some text
+
+#### subsection 1-1-2
+
+some text
+
+### subsection 1-2
+
+some text
+
+### subsection 1-3
+
+some text
+
+## section 2
+
+some text
+
+### subsection 2-1
+
+some text
+
+### subsection 2-1
+
+some text
+
+## section 3
+
+some text
+
+### subsection 3-1
+
+some text
+
+### subsection 3-2
+
+some text
+
+  `;
+
+  expect(await getHeadings(md)).toEqual([
+    {
+      children: [
+        {
+          children: [
+            {
+              children: [],
+              id: 'subsection-1-1-1',
+              level: 4,
+              value: 'subsection 1-1-1',
+            },
+            {
+              children: [],
+              id: 'subsection-1-1-2',
+              level: 4,
+              value: 'subsection 1-1-2',
+            },
+          ],
+          id: 'subsection-1-1',
+          level: 3,
+          value: 'subsection 1-1',
+        },
+        {children: [], id: 'subsection-1-2', level: 3, value: 'subsection 1-2'},
+        {children: [], id: 'subsection-1-3', level: 3, value: 'subsection 1-3'},
+      ],
+      id: 'section-1',
+      level: 2,
+      value: 'section 1',
+    },
+    {
+      children: [
+        {children: [], id: 'subsection-2-1', level: 3, value: 'subsection 2-1'},
+        {
+          children: [],
+          id: 'subsection-2-1-1',
+          level: 3,
+          value: 'subsection 2-1',
+        },
+      ],
+      id: 'section-2',
+      level: 2,
+      value: 'section 2',
+    },
+    {
+      children: [
+        {children: [], id: 'subsection-3-1', level: 3, value: 'subsection 3-1'},
+        {children: [], id: 'subsection-3-2', level: 3, value: 'subsection 3-2'},
+      ],
+      id: 'section-3',
+      level: 2,
+      value: 'section 3',
+    },
+  ]);
+});

package/src/remark/toc/{index.js → index.ts}

@@ -5,34 +5,42 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const {parse} = require('@babel/parser');
-const traverse = require('@babel/traverse').default;
-const stringifyObject = require('stringify-object');
-const search = require('./search');
+import {parse, ParserOptions} from '@babel/parser';
+import type {Identifier} from '@babel/types';
+import traverse from '@babel/traverse';
+import stringifyObject from 'stringify-object';
+import search from './search';
+import type {Plugin, Transformer} from 'unified';
+import type {Node, Parent} from 'unist';
+import type {Literal} from 'mdast';
 
-const parseOptions = {
+const parseOptions: ParserOptions = {
   plugins: ['jsx'],
   sourceType: 'module',
 };
-const isImport = (child) => child.type === 'import';
-const hasImports = (index) => index > -1;
-const isExport = (child) => child.type === 'export';
 
-const isTarget = (child, name) => {
+const isImport = (child: Node): child is Literal => child.type === 'import';
+const hasImports = (index: number) => index > -1;
+const isExport = (child: Node): child is Literal => child.type === 'export';
+
+interface PluginOptions {
+  name?: string;
+}
+
+const isTarget = (child: Literal, name: string) => {
   let found = false;
   const ast = parse(child.value, parseOptions);
   traverse(ast, {
     VariableDeclarator: (path) => {
-      if (path.node.id.name === name) {
+      if ((path.node.id as Identifier).name === name) {
         found = true;
       }
     },
   });
-
   return found;
 };
 
-const getOrCreateExistingTargetIndex = (children, name) => {
+const getOrCreateExistingTargetIndex = (children: Node[], name: string) => {
   let importsIndex = -1;
   let targetIndex = -1;
 
@@ -58,12 +66,12 @@ const getOrCreateExistingTargetIndex = (children, name) => {
   return targetIndex;
 };
 
-const plugin = (options = {}) => {
+const plugin: Plugin<[PluginOptions?]> = (options = {}) => {
   const name = options.name || 'toc';
 
-  const transformer = (node) => {
+  const transformer: Transformer = (node) => {
     const headings = search(node);
-    const {children} = node;
+    const {children} = node as Parent<Literal>;
     const targetIndex = getOrCreateExistingTargetIndex(children, name);
 
     if (headings && headings.length) {
@@ -76,4 +84,4 @@ const plugin = (options = {}) => {
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;

package/src/remark/toc/search.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import toString from 'mdast-util-to-string';
+import visit, {Visitor} from 'unist-util-visit';
+import {toValue} from '../utils';
+import type {TOCItem} from '@docusaurus/types';
+import type {Node} from 'unist';
+import type {Heading} from 'mdast';
+
+// Intermediate interface for TOC algorithm
+interface SearchItem {
+  node: TOCItem;
+  level: number;
+  parentIndex: number;
+}
+
+/**
+ *
+ * Generate a TOC AST from the raw Markdown contents
+ */
+export default function search(node: Node): TOCItem[] {
+  const headings: SearchItem[] = [];
+
+  const visitor: Visitor<Heading> = (child, _index, parent) => {
+    const value = toString(child);
+
+    // depth:1 headings are titles and not included in the TOC
+    if (parent !== node || !value || child.depth < 2) {
+      return;
+    }
+
+    headings.push({
+      node: {
+        value: toValue(child),
+        id: child.data!.id as string,
+        children: [],
+        level: child.depth,
+      },
+      level: child.depth,
+      parentIndex: -1,
+    });
+  };
+
+  visit(node, 'heading', visitor);
+
+  // Keep track of which previous index would be the current heading's direcy parent.
+  // Each entry <i> is the last index of the `headings` array at heading level <i>.
+  // We will modify these indices as we iterate through all headings.
+  // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
+  // indices 0 and 1 will remain unused.
+  const prevIndexForLevel = Array(7).fill(-1);
+
+  headings.forEach((curr, currIndex) => {
+    // take the last seen index for each ancestor level. the highest
+    // index will be the direct ancestor of the current heading.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // mark that curr.level was last seen at the current index
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodeIndexes: number[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading, i) => {
+    if (heading.parentIndex >= 0) {
+      headings[heading.parentIndex].node.children.push(heading.node);
+    } else {
+      rootNodeIndexes.push(i);
+    }
+  });
+
+  const toc = headings
+    .filter((_, k) => rootNodeIndexes.includes(k)) // only return root nodes
+    .map((heading) => heading.node); // only return Node, no metadata
+  return toc;
+}

package/src/remark/transformImage/__tests__/__fixtures__/img.md

@@ -0,0 +1,19 @@
+![img](https://example.com/img.png)
+
+![](./static/img.png)
+
+![img](./static/img.png)
+
+![img from second static folder](/img2.png)
+
+![img from second static folder](./static2/img2.png)
+
+![img](./static/img.png 'Title') ![img](/img.png)
+
+![img with "quotes"](./static/img.png ''Quoted' title')
+
+## Heading
+
+```md
+![img](./static/img.png)
+```

package/src/remark/transformImage/__tests__/__snapshots__/index.test.ts.snap

@@ -0,0 +1,33 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`transformImage plugin fail if image does not exist 1`] = `"Image packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/static/img/doesNotExist.png or packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/static2/img/doesNotExist.png used in packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/fail.md not found."`;
+
+exports[`transformImage plugin fail if image url is absent 1`] = `"Markdown image URL is mandatory in \\"packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/noUrl.md\\" file"`;
+
+exports[`transformImage plugin pathname protocol 1`] = `
+"![img](/img/unchecked.png)
+"
+`;
+
+exports[`transformImage plugin transform md images to <img /> 1`] = `
+"![img](https://example.com/img.png)
+
+<img src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!./static/img.png\\").default} />
+
+<img alt={\\"img\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!./static/img.png\\").default} />
+
+<img alt={\\"img from second static folder\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/static2/img2.png\\").default} />
+
+<img alt={\\"img from second static folder\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!./static2/img2.png\\").default} />
+
+<img alt={\\"img\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!./static/img.png\\").default} title=\\"Title\\" /> <img alt={\\"img\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!packages/docusaurus-mdx-loader/src/remark/transformImage/__tests__/__fixtures__/static/img.png\\").default} />
+
+<img alt={\\"img with &quot;quotes&quot;\\"} src={require(\\"![CWD]/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=[CWD]/node_modules/file-loader/dist/cjs.js!./static/img.png\\").default} title=\\"&#39;Quoted&#39; title\\" />
+
+## Heading
+
+\`\`\`md
+![img](./static/img.png)
+\`\`\`
+"
+`;