docs: normalize plugin API documentation (#6193)

* docs: normalize plugin API documentation * Revert change * Use remark plugin * edits * edit again * Fixes
2025-08-03 00:39:45 +02:00 · 2021-12-28 21:23:27 +08:00 · 2021-12-28 21:23:27 +08:00 · 5132ecdeee
commit 5132ecdeee
parent e067ce7ab5
12 changed files with 393 additions and 351 deletions
--- a/website/src/remark/configTabs.js
+++ b/website/src/remark/configTabs.js
@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+
+const visit = require('unist-util-visit');
+
+/**
+ * Turns a "```js config-tabs" code block into a "plugin options" and a "preset options" tab
+ */
+const plugin = () => {
+  const transformer = (root) => {
+    let tabsImported = false;
+    let codeBlockImported = false;
+    let transformed = false;
+    visit(root, ['code', 'import'], (node, index, parent) => {
+      if (node.type === 'import') {
+        if (node.value.includes('@theme/Tabs')) {
+          tabsImported = true;
+        } else if (node.value.includes('@theme/CodeBlock')) {
+          codeBlockImported = true;
+        }
+      } else if (node.meta?.includes('config-tabs')) {
+        transformed = true;
+        const {value} = node;
+        const [presetMeta, pluginMeta] = value.split('\n');
+        const {
+          groups: {presetOptionName},
+        } = presetMeta.match(
+          /preset option name: (?<presetOptionName>[A-Za-z]+)/i,
+        );
+        const {
+          groups: {pluginName},
+        } = pluginMeta.match(/plugin name: (?<pluginName>[A-Za-z@/-]+)/i);
+        // Replace leading "const config = " and trailing semi
+        const config = value
+          .replace(presetMeta, '')
+          .replace(pluginMeta, '')
+          .trim()
+          .replace(/^.*?= /, '')
+          .replace(/;$/, '')
+          .replace(/`/g, '\\`')
+          .replace(/\$/g, '\\$');
+        const newNodes = [
+          {
+            type: 'jsx',
+            value: `<Tabs>\n<TabItem value="Preset Options">`,
+          },
+          {
+            type: 'paragraph',
+            children: [
+              {
+                type: 'text',
+                value:
+                  'If you use a preset, configure this plugin through the ',
+              },
+              {
+                type: 'link',
+                title: null,
+                // TODO make this version-aware; maybe we need a useVersionedLink() hook
+                url: '/docs/presets#docusauruspreset-classic',
+                children: [
+                  {
+                    type: 'text',
+                    value: 'preset options',
+                  },
+                ],
+              },
+              {
+                type: 'text',
+                value: ':',
+              },
+            ],
+          },
+          {
+            type: 'jsx',
+            value: `<CodeBlock className="language-js" title="docusaurus.config.js">
+{\`module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        // highlight-start
+        ${presetOptionName}: ${config
+              .split('\n')
+              .map((line) => `        ${line}`)
+              .join('\n')
+              .trim()},
+        // highlight-end
+      },
+    ],
+  ],
+};\`}
+</CodeBlock>`,
+          },
+          {
+            type: 'jsx',
+            value: '</TabItem>\n<TabItem value="Plugin Options">',
+          },
+          {
+            type: 'paragraph',
+            children: [
+              {
+                type: 'text',
+                value:
+                  'If you are using a standalone plugin, provide options directly to the plugin:',
+              },
+            ],
+          },
+          {
+            type: 'jsx',
+            value: `<CodeBlock className="language-js" title="docusaurus.config.js">
+{\`module.exports = {
+  plugins: [
+    [
+      '${pluginName}',
+      // highlight-start
+      ${config
+        .split('\n')
+        .map((line) => `      ${line}`)
+        .join('\n')
+        .trim()},
+      // highlight-end
+    ],
+  ],
+};\`}
+</CodeBlock>`,
+          },
+          {
+            type: 'jsx',
+            value: '</TabItem>\n</Tabs>',
+          },
+        ];
+        parent.children.splice(index, 1, ...newNodes);
+      }
+    });
+    if (transformed) {
+      if (!tabsImported) {
+        root.children.unshift({
+          type: 'import',
+          value:
+            "import Tabs from '@theme/Tabs';\nimport TabItem from '@theme/TabItem';",
+        });
+      }
+      if (!codeBlockImported) {
+        root.children.unshift({
+          type: 'import',
+          value: "import CodeBlock from '@theme/CodeBlock';",
+        });
+      }
+    }
+  };
+  return transformer;
+};
+
+module.exports = plugin;