@docusaurus/mdx-loader 2.0.0-beta.7babfe036 → 2.0.0-beta.8

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/{index.js → index.ts}

@@ -5,26 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const visit = require('unist-util-visit');
-const path = require('path');
-const url = require('url');
-const fs = require('fs-extra');
-const escapeHtml = require('escape-html');
-const {getFileLoaderUtils} = require('@docusaurus/core/lib/webpack/utils');
-const {
+import visit from 'unist-util-visit';
+import path from 'path';
+import url from 'url';
+import fs from 'fs-extra';
+import escapeHtml from 'escape-html';
+import {getFileLoaderUtils} from '@docusaurus/core/lib/webpack/utils';
+import {
   posixPath,
   escapePath,
   toMessageRelativeFilePath,
-} = require('@docusaurus/utils');
+} from '@docusaurus/utils';
+import type {Plugin, Transformer} from 'unified';
+import type {Image, Literal} from 'mdast';
 
 const {
   loaders: {inlineMarkdownImageFileLoader},
 } = getFileLoaderUtils();
 
-const createJSX = (node, pathUrl) => {
+interface PluginOptions {
+  filePath: string;
+  staticDir: string;
+}
+
+const createJSX = (node: Image, pathUrl: string) => {
   const jsxNode = node;
-  jsxNode.type = 'jsx';
-  jsxNode.value = `<img ${node.alt ? `alt={"${escapeHtml(node.alt)}"} ` : ''}${
+  (jsxNode as unknown as Literal).type = 'jsx';
+  (jsxNode as unknown as Literal).value = `<img ${
+    node.alt ? `alt={"${escapeHtml(node.alt)}"} ` : ''
+  }${
     node.url
       ? `src={require("${inlineMarkdownImageFileLoader}${escapePath(
           pathUrl,
@@ -33,7 +42,7 @@ const createJSX = (node, pathUrl) => {
   }${node.title ? ` title="${escapeHtml(node.title)}"` : ''} />`;
 
   if (jsxNode.url) {
-    delete jsxNode.url;
+    delete (jsxNode as Partial<Image>).url;
   }
   if (jsxNode.alt) {
     delete jsxNode.alt;
@@ -43,7 +52,7 @@ const createJSX = (node, pathUrl) => {
   }
 };
 
-async function ensureImageFileExist(imagePath, sourceFilePath) {
+async function ensureImageFileExist(imagePath: string, sourceFilePath: string) {
   const imageExists = await fs.pathExists(imagePath);
   if (!imageExists) {
     throw new Error(
@@ -54,7 +63,10 @@ async function ensureImageFileExist(imagePath, sourceFilePath) {
   }
 }
 
-async function processImageNode(node, {filePath, staticDir}) {
+async function processImageNode(
+  node: Image,
+  {filePath, staticDir}: PluginOptions,
+) {
   if (!node.url) {
     throw new Error(
       `Markdown image URL is mandatory in "${toMessageRelativeFilePath(
@@ -71,8 +83,6 @@ async function processImageNode(node, {filePath, staticDir}) {
     // it's mostly to make next release less risky (2.0.0-alpha.59)
     if (parsedUrl.protocol === 'pathname:') {
       node.url = node.url.replace('pathname://', '');
-    } else {
-      // noop
     }
   }
   // images without protocol
@@ -92,10 +102,10 @@ async function processImageNode(node, {filePath, staticDir}) {
   }
 }
 
-const plugin = (options) => {
-  const transformer = async (root) => {
-    const promises = [];
-    visit(root, 'image', (node) => {
+const plugin: Plugin<[PluginOptions]> = (options) => {
+  const transformer: Transformer = async (root) => {
+    const promises: Promise<void>[] = [];
+    visit(root, 'image', (node: Image) => {
       promises.push(processImageNode(node, options));
     });
     await Promise.all(promises);
@@ -103,4 +113,4 @@ const plugin = (options) => {
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;

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

@@ -14,7 +14,9 @@ exports[`transformAsset plugin transform md links to <a /> 1`] = `
 
 <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./asset.pdf').default}>asset</a>
 
-<a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./asset.pdf').default}title=\\"Title\\">asset</a>
+<a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./asset.pdf').default + '#page=2'}>asset with hash</a>
+
+<a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./asset.pdf').default} title=\\"Title\\">asset</a>
 
 ## Heading
 
@@ -32,6 +34,8 @@ exports[`transformAsset plugin transform md links to <a /> 1`] = `
 
 <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAsset.pdf').default}>@site/static/staticAsset.pdf</a>
 
+<a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAsset.pdf').default + '#page=2'} title=\\"Title\\">@site/static/staticAsset.pdf</a>
+
 <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAsset.pdf').default}>Just staticAsset.pdf</a>, and <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAsset.pdf').default}><strong>awesome</strong> staticAsset 2.pdf &#39;It is really &quot;AWESOME&quot;&#39;</a>, but also <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAsset.pdf').default}>coded <code>staticAsset 3.pdf</code></a>
 
 <a target=\\"_blank\\" href={require('!file-loader?name=assets/files/[name]-[hash].[ext]!./static/staticAssetImage.png').default}><img alt={\\"Clickable Docusaurus logo\\"} src={require(\\"!url-loader?limit=10000&name=assets/images/[name]-[hash].[ext]&fallback=file-loader!./static/staticAssetImage.png\\").default} /></a>

package/src/remark/transformLinks/__tests__/fixtures/asset.md

@@ -4,6 +4,8 @@
 
 [asset](./asset.pdf)
 
+[asset with hash](./asset.pdf#page=2)
+
 [asset](asset.pdf 'Title')
 
 ## Heading
@@ -22,6 +24,8 @@
 
 [@site/static/staticAsset.pdf](@site/static/staticAsset.pdf)
 
+[@site/static/staticAsset.pdf](@site/static/staticAsset.pdf#page=2 'Title')
+
 [Just staticAsset.pdf](/staticAsset.pdf), and [**awesome** staticAsset 2.pdf 'It is really "AWESOME"'](/staticAsset.pdf), but also [coded `staticAsset 3.pdf`](/staticAsset.pdf)
 
 [![Clickable Docusaurus logo](./static/staticAssetImage.png)](/staticAssetImage.png)