Added custom plugins for wrapping headings in sections / parsing table of contents based on sections from markdown

packages/website/mdx/guides/page-template.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-    id: 3523532,
+    id: 352353266,
     title: 'Page template',
     description: 'A relayer is any party or entity which hosts an off-chain orderbook.',
     tags: ['Relayer', 'Trader', 'Protocol Developer'],
@@ -17,7 +17,7 @@ Coverage subprovider needs some info about your contracts (`srcMap`, `bytecode`)
 
 In order to use `CoverageSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it.
 
-## Sol-compiler
+### Sol-compiler
 
 If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs/sol-compiler) you can use the `SolCompilerArtifactAdapter` we've implemented for you.
 
@@ -27,7 +27,7 @@ import { SolCompilerArtifactAdapter } from '@0x/sol-coverage';
 const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir);
 ```
 
-## Truffle
+### Truffle
 
 If your project is using [Truffle](https://truffleframework.com/), we've written a `TruffleArtifactsAdapter`for you.
 

packages/website/package.json

@@ -137,7 +137,6 @@
         "extract-mdx-metadata": "^1.0.0",
         "less-loader": "^4.1.0",
         "make-promises-safe": "^1.1.0",
-        "mdx-table-of-contents": "^0.1.0",
         "raw-loader": "^0.5.1",
         "react-svg-loader": "^2.1.0",
         "remark": "^10.0.1",
@@ -155,7 +154,9 @@
         "typescript": "3.0.1",
         "uglifyjs-webpack-plugin": "^2.0.1",
         "unist-util-filter": "^1.0.2",
+        "unist-util-find-after": "^2.0.4",
         "unist-util-select": "^2.0.2",
+        "unist-util-visit-parents": "^3.0.0",
         "webpack": "^4.20.2",
         "webpack-bundle-analyzer": "^3.0.3",
         "webpack-cli": "3.1.2",

packages/website/webpack.config.js

@@ -5,8 +5,9 @@ const TerserPlugin = require('terser-webpack-plugin');
 const RollbarSourceMapPlugin = require('rollbar-sourcemap-webpack-plugin');
 const childProcess = require('child_process');
 const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
-const mdxTableOfContents = require('mdx-table-of-contents');
 const remarkSlug = require('remark-slug');
+const sectionizeHeadings = require('./webpack/sectionize-headings');
+const mdxSectionTOC = require('./webpack/mdx-section-toc');
 
 const GIT_SHA = childProcess
     .execSync('git rev-parse HEAD')
@@ -80,8 +81,8 @@ const config = {
                     {
                         loader: '@mdx-js/loader',
                         options: {
-                            remarkPlugins: [remarkSlug],
-                            compilers: [mdxTableOfContents],
+                            remarkPlugins: [remarkSlug, sectionizeHeadings],
+                            compilers: [mdxSectionTOC],
                         },
                     },
                 ],

packages/website/webpack/mdx-section-toc.js

@@ -0,0 +1,110 @@
+const { toJSX } = require('@mdx-js/mdx/mdx-hast-to-jsx');
+
+function mdxTableOfContents(options = {}) {
+    let OldCompiler = this.Compiler;
+    let info;
+
+    this.Compiler = tree => {
+        let code = OldCompiler(tree, {}, options);
+
+        if (!info.hasTableOfContentsExport) {
+            code += `\nexport const tableOfContents = (components={}) => ${tableOfContentsListSerializer(
+                info.tableOfContents,
+            )}\n`;
+        }
+
+        return code;
+    };
+
+    return function transformer(node) {
+        info = getInfo(node, options);
+    };
+}
+
+function getInfo(root, { minLevel = 1, maxLevel = 3 } = {}) {
+    let info = {
+        hasFrontMatterExport: false,
+        hasTableOfContentsExport: false,
+        tableOfContents: [],
+    };
+
+    addSections(info.tableOfContents, root.children, minLevel, maxLevel);
+
+    return info;
+}
+
+function addSections(parent, children, minLevel, maxLevel) {
+    for (let i = 0; i < children.length; i++) {
+        let node = children[i];
+
+        if (node.type === 'export' && node.value.indexOf('tableOfContents') !== -1) {
+            info.hasTableOfContentsExport = true;
+        }
+
+        if (isSlugifiedSection(node)) {
+            let level = node.properties.depth;
+
+            if (level >= minLevel && level <= maxLevel) {
+                let id = node.properties.id;
+
+                let item = {
+                    id,
+                    level,
+                    title: toFragment(node.children[0].children),
+                    children: [],
+                };
+
+                if (parent.children) {
+                    parent.children.push(item);
+                } else {
+                    parent.push(item);
+                }
+
+                addSections(item, node.children, minLevel, maxLevel);
+            }
+        }
+    }
+}
+
+function isSlugifiedSection(node) {
+    return node.tagName === 'section' && node.properties && node.properties.id && node.properties.depth;
+}
+
+function toFragment(nodes) {
+    if (nodes.length === 1 && nodes[0].type === 'text') {
+        return JSON.stringify(nodes[0].value);
+    } else {
+        return '<React.Fragment>' + nodes.map(toJSX).join('') + '</React.Fragment>';
+    }
+}
+
+function tableOfContentsListSerializer(nodes, indent = 0) {
+    return indentString(
+        indent,
+        `[
+  ${nodes.map(node => tableOfContentsNodeSerializer(node, indent + 2)).join(',\n')}
+]`,
+    );
+}
+
+function tableOfContentsNodeSerializer(node, indent = 0) {
+    return indentString(
+        indent,
+        `{
+  id: ${JSON.stringify(node.id)},
+  level: ${node.level},
+  title: ${node.title},
+  children: ${tableOfContentsListSerializer(node.children, indent + 2)}
+}`,
+    );
+}
+
+function indentString(size, string) {
+    return string
+        .split('\n')
+        .map(x => ' '.repeat(size) + x)
+        .join('\n')
+        .trim();
+}
+
+module.exports = mdxTableOfContents;

packages/website/webpack/sectionize-headings.js

@@ -0,0 +1,50 @@
+const findAfter = require('unist-util-find-after');
+const visit = require('unist-util-visit-parents');
+
+const MAX_HEADING_DEPTH = 6;
+
+module.exports = plugin;
+
+function plugin() {
+    return transform;
+}
+
+function transform(tree) {
+    for (let depth = MAX_HEADING_DEPTH; depth > 0; depth--) {
+        visit(tree, node => node.type === 'heading' && node.depth === depth, sectionize);
+    }
+}
+
+function sectionize(node, ancestors) {
+    const start = node;
+    const parent = ancestors[ancestors.length - 1];
+
+    const isEnd = node => node.type === 'heading' && node.depth <= start.depth;
+    const end = findAfter(parent, start, isEnd);
+
+    const startIndex = parent.children.indexOf(start);
+    const endIndex = parent.children.indexOf(end);
+
+    const between = parent.children.slice(startIndex, endIndex > 0 ? endIndex : undefined);
+
+    // We want to grab the ids created by remark-slug based on heading values
+    // node (heading) data has this shape now:
+    // { hProperties: { id: 'some-id' }, id: 'some-id' } }
+    // depth is the heading size (i.e. 2 for h2)
+    const { data, depth } = node;
+    // We combine the two for section data
+    const sectionData = { ...data, hProperties: { ...data.hProperties, depth } };
+    // and then remove data (ids) from the heading nodes
+    node.data = {};
+    // A section node is created with the data grabbed above
+    const section = {
+        type: 'section',
+        children: between,
+        data: {
+            ...sectionData,
+            hName: 'section',
+        },
+    };
+
+    parent.children.splice(startIndex, section.children.length, section);
+}

yarn.lock

@@ -2274,20 +2274,6 @@
     unist-builder "^1.0.1"
     unist-util-visit "^1.3.0"
 
-"@mdx-js/mdx@^0.15.5":
-  version "0.15.7"
-  resolved "https://registry.yarnpkg.com/@mdx-js/mdx/-/mdx-0.15.7.tgz#5fde5841d7b6f4c78f80c19fff559532af5ce5ad"
-  integrity sha512-bWUQidQhjTRFh5nK01kW3qQLCH/aCq6VTapOZ/+WI5hL4exoRw6TgnxxmgSf/p7mmrGxIpCHmnaWXdbHSObxlg==
-  dependencies:
-    change-case "^3.0.2"
-    detab "^2.0.0"
-    mdast-util-to-hast "^3.0.0"
-    remark-parse "^5.0.0"
-    remark-squeeze-paragraphs "^3.0.1"
-    to-style "^1.3.3"
-    unified "^6.1.6"
-    unist-util-visit "^1.3.0"
-
 "@mdx-js/mdx@^1.0.0-rc.4":
   version "1.0.21"
   resolved "https://registry.yarnpkg.com/@mdx-js/mdx/-/mdx-1.0.21.tgz#028a7975fff026222f7ace19c8c130290c649025"
@@ -2889,7 +2875,7 @@
   dependencies:
     source-map "^0.6.1"
 
-"@types/unist@*", "@types/unist@^2.0.0", "@types/unist@^2.0.2":
+"@types/unist@*", "@types/unist@^2.0.0", "@types/unist@^2.0.2", "@types/unist@^2.0.3":
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/@types/unist/-/unist-2.0.3.tgz#9c088679876f374eb5983f150d4787aa6fb32d7e"
 
@@ -9733,11 +9719,23 @@ got@^6.7.1:
     unzip-response "^2.0.1"
     url-parse-lax "^1.0.0"
 
-graceful-fs@4.1.15, graceful-fs@^3.0.0, graceful-fs@^4.0.0, graceful-fs@^4.1.10, graceful-fs@^4.1.11, graceful-fs@^4.1.2, graceful-fs@^4.1.6, graceful-fs@^4.1.9, graceful-fs@~1.2.0:
+graceful-fs@^3.0.0:
+  version "3.0.11"
+  resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-3.0.11.tgz#7613c778a1afea62f25c630a086d7f3acbbdd818"
+  integrity sha1-dhPHeKGv6mLyXGMKCG1/Osu92Bg=
+  dependencies:
+    natives "^1.1.0"
+
+graceful-fs@^4.0.0, graceful-fs@^4.1.10, graceful-fs@^4.1.11, graceful-fs@^4.1.2, graceful-fs@^4.1.6, graceful-fs@^4.1.9:
   version "4.1.15"
   resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.1.15.tgz#ffb703e1066e8a0eeaa4c8b80ba9253eeefbfb00"
   integrity sha512-6uHUhOPEBgQ24HM+r6b/QwWfZq+yiFcipKFrOFiBEnWdy5sdzYoi+pJeQaPI5qOLRFqWmAXUPQNsielzdLoecA==
 
+graceful-fs@~1.2.0:
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-1.2.3.tgz#15a4806a57547cb2d2dbf27f42e89a8c3451b364"
+  integrity sha1-FaSAaldUfLLS2/J/QuiajDRRs2Q=
+
 "graceful-readlink@>= 1.0.0":
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/graceful-readlink/-/graceful-readlink-1.0.1.tgz#4cafad76bc62f02fa039b2f94e9a3dd3a391a725"
@@ -12915,23 +12913,6 @@ mdast-util-definitions@^1.2.0:
   dependencies:
     unist-util-visit "^1.0.0"
 
-mdast-util-to-hast@^3.0.0:
-  version "3.0.4"
-  resolved "https://registry.yarnpkg.com/mdast-util-to-hast/-/mdast-util-to-hast-3.0.4.tgz#132001b266031192348d3366a6b011f28e54dc40"
-  integrity sha512-/eIbly2YmyVgpJNo+bFLLMCI1XgolO/Ffowhf+pHDq3X4/V6FntC9sGQCDLM147eTS+uSXv5dRzJyFn+o0tazA==
-  dependencies:
-    collapse-white-space "^1.0.0"
-    detab "^2.0.0"
-    mdast-util-definitions "^1.2.0"
-    mdurl "^1.0.1"
-    trim "0.0.1"
-    trim-lines "^1.0.0"
-    unist-builder "^1.0.1"
-    unist-util-generated "^1.1.0"
-    unist-util-position "^3.0.0"
-    unist-util-visit "^1.1.0"
-    xtend "^4.0.1"
-
 mdast-util-to-hast@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/mdast-util-to-hast/-/mdast-util-to-hast-4.0.0.tgz#d8467ce28ea73b4648667bc389aa39dfa9f67f18"
@@ -12957,13 +12938,6 @@ mdurl@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/mdurl/-/mdurl-1.0.1.tgz#fe85b2ec75a59037f2adfec100fd6c601761152e"
 
-mdx-table-of-contents@^0.1.0:
-  version "0.1.0"
-  resolved "https://registry.yarnpkg.com/mdx-table-of-contents/-/mdx-table-of-contents-0.1.0.tgz#a09dce9424ddff084ab07b7a6f3dcba5ed456fb3"
-  integrity sha512-aNhJvAkghJEKLat+THHJB9qi2bS4iBl1wNDLfwbByUZTvQ8DgLKUJ/TMEIrcWMuuks6BbsK7sp2IqLTUPnUfZQ==
-  dependencies:
-    "@mdx-js/mdx" "^0.15.5"
-
 media-typer@0.3.0:
   version "0.3.0"
   resolved "https://registry.yarnpkg.com/media-typer/-/media-typer-0.3.0.tgz#8710d7af0aa626f8fffa1ce00168545263255748"
@@ -13521,6 +13495,11 @@ nanomatch@^1.2.9:
     snapdragon "^0.8.1"
     to-regex "^3.0.1"
 
+natives@^1.1.0:
+  version "1.1.6"
+  resolved "https://registry.yarnpkg.com/natives/-/natives-1.1.6.tgz#a603b4a498ab77173612b9ea1acdec4d980f00bb"
+  integrity sha512-6+TDFewD4yxY14ptjKaS63GVdtKiES1pTPyxn9Jb0rBqPMZ7VcCiooEhPNsr+mqHtMGxa/5c/HhcC4uPEUw/nA==
+
 natural-compare@^1.4.0:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7"
@@ -19486,18 +19465,6 @@ unified@^6.1.5:
     x-is-function "^1.0.4"
     x-is-string "^0.1.0"
 
-unified@^6.1.6:
-  version "6.2.0"
-  resolved "https://registry.yarnpkg.com/unified/-/unified-6.2.0.tgz#7fbd630f719126d67d40c644b7e3f617035f6dba"
-  integrity sha512-1k+KPhlVtqmG99RaTbAv/usu85fcSRu3wY8X+vnsEhIxNP5VbVIDiXnLqyKIG+UMdyTg0ZX9EI6k2AfjJkHPtA==
-  dependencies:
-    bail "^1.0.0"
-    extend "^3.0.0"
-    is-plain-obj "^1.1.0"
-    trough "^1.0.0"
-    vfile "^2.0.0"
-    x-is-string "^0.1.0"
-
 unified@^7.0.0:
   version "7.1.0"
   resolved "https://registry.yarnpkg.com/unified/-/unified-7.1.0.tgz#5032f1c1ee3364bd09da12e27fdd4a7553c7be13"
@@ -19589,6 +19556,13 @@ unist-util-filter@^1.0.2:
     flatmap "0.0.3"
     unist-util-is "^3.0.0"
 
+unist-util-find-after@^2.0.4:
+  version "2.0.4"
+  resolved "https://registry.yarnpkg.com/unist-util-find-after/-/unist-util-find-after-2.0.4.tgz#3fcccf0df3a2e7291fa119224c0f22158357cc10"
+  integrity sha512-zo0ShIr+E/aU9xSK7JC9Kb+WP9seTFCuqVYdo5+HJSjN009XMfhiA1FIExEKzdDP1UsgvKGleGlB/pSdTSqZww==
+  dependencies:
+    unist-util-is "^3.0.0"
+
 unist-util-generated@^1.1.0:
   version "1.1.4"
   resolved "https://registry.yarnpkg.com/unist-util-generated/-/unist-util-generated-1.1.4.tgz#2261c033d9fc23fae41872cdb7663746e972c1a7"
@@ -19601,6 +19575,11 @@ unist-util-is@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/unist-util-is/-/unist-util-is-3.0.0.tgz#d9e84381c2468e82629e4a5be9d7d05a2dd324cd"
 
+unist-util-is@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/unist-util-is/-/unist-util-is-4.0.0.tgz#85672993f0d88a8bffb45137aba003ee8da11a38"
+  integrity sha512-E5JLUKRQlAYiJmN2PVBdSz01R3rUKRSM00X+0DB/yLqxdLu6wZZkRdTIsxDp9X+bkxh8Eq+O2YYRbZvLZtQT1A==
+
 unist-util-position@^3.0.0:
   version "3.0.3"
   resolved "https://registry.yarnpkg.com/unist-util-position/-/unist-util-position-3.0.3.tgz#fff942b879538b242096c148153826664b1ca373"
@@ -19649,6 +19628,14 @@ unist-util-visit-parents@^2.0.0:
   dependencies:
     unist-util-is "^3.0.0"
 
+unist-util-visit-parents@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/unist-util-visit-parents/-/unist-util-visit-parents-3.0.0.tgz#dd4cdcd86d505ec7a81bdc01bc790f9def742bee"
+  integrity sha512-H3K8d81S4V3XVXVwLvrLGk+R5VILryfUotD06/R/rLsTsPLGjkn6gIP8qEEVITcuIySNYj0ocJLsePjm9F/Vcg==
+  dependencies:
+    "@types/unist" "^2.0.3"
+    unist-util-is "^4.0.0"
+
 unist-util-visit@1.4.0:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/unist-util-visit/-/unist-util-visit-1.4.0.tgz#1cb763647186dc26f5e1df5db6bd1e48b3cc2fb1"