feat(v2): support rightToc, emoji, slug for docs (#1382)

* add remark-slug and remark-emoji

* implement right TOC remark plugin

* use rehype-slug ecosystem instead of remark for perf

* first rough implementation for right toc

* nits

* remove unwanted changes

* fix left border styling

* remove depths

* inline snapshot

packages/docusaurus-mdx-loader/src/index.js

@@ -7,9 +7,13 @@
 const {getOptions} = require('loader-utils');
 const mdx = require('@mdx-js/mdx');
 const rehypePrism = require('@mapbox/rehype-prism');
+const emoji = require('remark-emoji');
+const slug = require('rehype-slug');
+const rightToc = require('./rightToc');
 
 const DEFAULT_OPTIONS = {
-  rehypePlugins: [[rehypePrism, {ignoreMissing: true}]],
+  rehypePlugins: [slug, [(rehypePrism, {ignoreMissing: true})]],
+  remarkPlugins: [emoji, rightToc],
   prismTheme: 'prism-themes/themes/prism-atom-dark.css',
 };
 

packages/docusaurus-mdx-loader/src/rightToc/__tests__/fixtures/empty-headings.mdx

@@ -0,0 +1,5 @@
+# Ignore this
+
+## 
+
+## ![](an-image.svg)

packages/docusaurus-mdx-loader/src/rightToc/__tests__/fixtures/insert-below-imports.mdx

@@ -0,0 +1,11 @@
+import something from 'something';
+
+import somethingElse from 'something-else';
+
+## Title
+
+## Test
+
+### Again
+
+Content.

packages/docusaurus-mdx-loader/src/rightToc/__tests__/fixtures/just-content.mdx

@@ -0,0 +1,15 @@
+### Endi
+
+```md
+## This is ignored
+```
+
+## Endi
+
+Lorem ipsum
+
+### Yangshun
+
+Some content here
+
+## I ♥ unicode.

packages/docusaurus-mdx-loader/src/rightToc/__tests__/fixtures/name-exist.mdx

@@ -0,0 +1,7 @@
+export const rightToc = ['replaceMe'];
+
+## Thanos
+
+## Tony Stark
+
+### Avengers

packages/docusaurus-mdx-loader/src/rightToc/__tests__/index.test.js

@@ -0,0 +1,200 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import '@babel/polyfill';
+import {join} from 'path';
+import remark from 'remark';
+import mdx from 'remark-mdx';
+import vfile from 'to-vfile';
+import plugin from '../index';
+
+const processFixture = async (name, options) => {
+  const path = join(__dirname, 'fixtures', `${name}.mdx`);
+  const file = await vfile.read(path);
+  const result = await remark()
+    .use(mdx)
+    .use(plugin, options)
+    .process(file);
+
+  return result.toString();
+};
+
+test('no options', async () => {
+  const result = await processFixture('just-content');
+  expect(result).toMatchInlineSnapshot(`
+"export const rightToc = [
+	{
+		value: 'Endi',
+		id: 'endi',
+		children: []
+	},
+	{
+		value: 'Endi',
+		id: 'endi-1',
+		children: [
+			{
+				value: 'Yangshun',
+				id: 'yangshun',
+				children: []
+			}
+		]
+	},
+	{
+		value: 'I ♥ unicode.',
+		id: 'i--unicode',
+		children: []
+	}
+];
+
+### Endi
+
+\`\`\`md
+## This is ignored
+\`\`\`
+
+## Endi
+
+Lorem ipsum
+
+### Yangshun
+
+Some content here
+
+## I ♥ unicode.
+"
+`);
+});
+
+test('should export even with existing name', async () => {
+  const result = await processFixture('name-exist');
+  expect(result).toMatchInlineSnapshot(`
+"export const rightToc = [
+	{
+		value: 'Thanos',
+		id: 'thanos',
+		children: []
+	},
+	{
+		value: 'Tony Stark',
+		id: 'tony-stark',
+		children: [
+			{
+				value: 'Avengers',
+				id: 'avengers',
+				children: []
+			}
+		]
+	}
+];
+
+## Thanos
+
+## Tony Stark
+
+### Avengers
+"
+`);
+});
+
+test('should export with custom name', async () => {
+  const options = {
+    name: 'customName',
+  };
+  const result = await processFixture('just-content', options);
+  expect(result).toMatchInlineSnapshot(`
+"export const customName = [
+	{
+		value: 'Endi',
+		id: 'endi',
+		children: []
+	},
+	{
+		value: 'Endi',
+		id: 'endi-1',
+		children: [
+			{
+				value: 'Yangshun',
+				id: 'yangshun',
+				children: []
+			}
+		]
+	},
+	{
+		value: 'I ♥ unicode.',
+		id: 'i--unicode',
+		children: []
+	}
+];
+
+### Endi
+
+\`\`\`md
+## This is ignored
+\`\`\`
+
+## Endi
+
+Lorem ipsum
+
+### Yangshun
+
+Some content here
+
+## I ♥ unicode.
+"
+`);
+});
+
+test('should insert below imports', async () => {
+  const result = await processFixture('insert-below-imports');
+  expect(result).toMatchInlineSnapshot(`
+"import something from 'something';
+
+import somethingElse from 'something-else';
+
+export const rightToc = [
+	{
+		value: 'Title',
+		id: 'title',
+		children: []
+	},
+	{
+		value: 'Test',
+		id: 'test',
+		children: [
+			{
+				value: 'Again',
+				id: 'again',
+				children: []
+			}
+		]
+	}
+];
+
+## Title
+
+## Test
+
+### Again
+
+Content.
+"
+`);
+});
+
+test('empty headings', async () => {
+  const result = await processFixture('empty-headings');
+  expect(result).toMatchInlineSnapshot(`
+"export const rightToc = [];
+
+# Ignore this
+
+## 
+
+## ![](an-image.svg)
+"
+`);
+});

packages/docusaurus-mdx-loader/src/rightToc/index.js

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * 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');
+
+const parseOptions = {
+  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) => {
+  let found = false;
+  const ast = parse(child.value, parseOptions);
+  traverse(ast, {
+    VariableDeclarator: path => {
+      if (path.node.id.name === name) {
+        found = true;
+      }
+    },
+  });
+
+  return found;
+};
+
+const getOrCreateExistingTargetIndex = (children, name) => {
+  let importsIndex = -1;
+  let targetIndex = -1;
+
+  children.forEach((child, index) => {
+    if (isImport(child)) {
+      importsIndex = index;
+    } else if (isExport(child) && isTarget(child, name)) {
+      targetIndex = index;
+    }
+  });
+
+  if (targetIndex === -1) {
+    const target = {
+      default: false,
+      type: 'export',
+      value: `export const ${name} = [];`,
+    };
+
+    targetIndex = hasImports(importsIndex) ? importsIndex + 1 : 0;
+    children.splice(targetIndex, 0, target);
+  }
+
+  return targetIndex;
+};
+
+const plugin = (options = {}) => {
+  const name = options.name || 'rightToc';
+
+  const transformer = node => {
+    const headings = search(node);
+    const {children} = node;
+    const targetIndex = getOrCreateExistingTargetIndex(children, name);
+
+    if (headings && headings.length) {
+      children[targetIndex].value = `export const ${name} = ${stringifyObject(
+        headings,
+      )};`;
+    }
+  };
+
+  return transformer;
+};
+
+module.exports = plugin;

packages/docusaurus-mdx-loader/src/rightToc/search.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const toString = require('mdast-util-to-string');
+const visit = require('unist-util-visit');
+const slugs = require('github-slugger')();
+
+// Visit all headings. We `slug` all headings (to account for
+// duplicates), but only take h2 and h3 headings.
+const search = node => {
+  const headings = [];
+  let current = -1;
+  let currentDepth = 0;
+
+  slugs.reset();
+
+  const onHeading = (child, index, parent) => {
+    const value = toString(child);
+    const id =
+      child.data && child.data.hProperties && child.data.hProperties.id;
+    const slug = slugs.slug(id || value);
+
+    if (parent !== node || !value || child.depth > 3 || child.depth < 2) {
+      return;
+    }
+
+    const entry = {value, id: slug, children: []};
+
+    if (!headings.length || currentDepth >= child.depth) {
+      headings.push(entry);
+      current += 1;
+      currentDepth = child.depth;
+    } else {
+      headings[current].children.push(entry);
+    }
+  };
+
+  visit(node, 'heading', onHeading);
+
+  return headings;
+};
+
+module.exports = search;