chore: automate plugin page headings

svg · May 15, 2024 · fd68840 · fd68840
1 parent 6a572fa
commit fd68840
Show file tree

Hide file tree

Showing 5 changed files with 88 additions and 15 deletions.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -1,15 +1,15 @@
 const { themes } = require('prism-react-renderer');
 
 /**
- * @typedef {import("@docusaurus/types").Config} Config 
+ * @typedef {import("@docusaurus/types").Config} Config
  */
 
 /**
  * Config for Docusaurus.
- * 
- * $.themeConfig.navbar.logo is underfined as this is configured with a custom component.
+ *
+ * $.themeConfig.navbar.logo is undefined as this is configured with a custom component.
  * $.themeConfig.footer.style is ignored as this is overriden with custom CSS.
- * 
+ *
  * @type {Config}
  */
 const config = {

diff --git a/src/css/custom.css b/src/css/custom.css
@@ -50,6 +50,11 @@
   }
 }
 
+/* TOC overrides */
+.table-of-contents__link--active {
+  color: var(--svgo-pri-fg-color);
+}
+
 /* Search overrides */
 nav input {
   background-color: var(--svgo-search-bg-color) !important;

diff --git a/src/theme/DocItem/Content/index.js b/src/theme/DocItem/Content/index.js
@@ -6,6 +6,9 @@ import Heading from '@theme/Heading';
 import MDXContent from '@theme/MDXContent';
 import DefaultBadge from '../../../components/DefaulBadge';
 import styles from './index.module.css';
+import PluginUsage from '../../../components/PluginUsage';
+import PluginParams from '../../../components/PluginParams';
+import PluginDemo from '../../../components/PluginDemo';
 
 function useSyntheticTitle(metadata, frontMatter, contentTitle) {
   const shouldRender =
@@ -35,6 +38,23 @@ export default function DocItemContent({ children }) {
         </header>
       )}
       <MDXContent>{children}</MDXContent>
+
+      {frontMatter.svgo?.pluginId && (
+        <>
+          <h2 id="usage">Usage</h2>
+          <PluginUsage />
+
+          {frontMatter.svgo?.parameters && (
+            <>
+              <h3 id="parameters">Parameters</h3>
+              <PluginParams />
+            </>
+          )}
+
+          <h2 id="demo">Demo</h2>
+          <PluginDemo/>
+        </>
+      )}
     </div>
   );
 }
diff --git a/src/theme/TOCItems/Tree.js b/src/theme/TOCItems/Tree.js
@@ -4,8 +4,40 @@ import { useDoc } from '@docusaurus/theme-common/internal';
 import Translate from '@docusaurus/Translate';
 import styles from './index.module.css';
 
+/**
+ * This is a hack to dynamically insert TOC items into the plugin pages table
+ * of contents. Normally, only headings inserted in the Markdown or MDX file
+ * will appear in the TOC, which excludes headings specified in React
+ * components.
+ *
+ * By doing this, we can insert the TOC headings despite them being declared in
+ * React components.
+ *
+ * @param {array} toc
+ * @param {object} svgoFrontMatter
+ */
+function insertPluginTocItems(toc, svgoFrontMatter) {
+  const usageChildren = []
+
+  if (svgoFrontMatter.parameters) {
+    usageChildren.push({
+      children: [],
+      id: "parameters",
+      level: 3,
+      value: "Parameters",
+    });
+  }
+
+  toc.push({ children: usageChildren, toc, id: "usage", level: 2, value: "Usage" });
+  toc.push({ children: [], toc, id: "demo", level: 2, value: "Demo" });
+}
+
 function TOCItemTree({ toc, className, linkClassName, isChild }) {
-  const { metadata } = useDoc();
+  const { metadata, frontMatter } = useDoc();
+
+  if (toc && !isChild && frontMatter.svgo?.pluginId) {
+    insertPluginTocItems(toc, frontMatter.svgo);
+  }
 
   if (!toc.length) {
     return null;
@@ -38,14 +70,27 @@ function TOCItemTree({ toc, className, linkClassName, isChild }) {
         ))}
       </ul>
       {!isChild && (
-        <div className={clsx(styles.editPage)}>
-          <a
-            href={editUrl}
-            target="_blank"
-            className={linkClassName ?? undefined}
-          >
-            <Translate>Edit this page on GitHub</Translate>
-          </a>
+        <div className={clsx(styles.topBorder)}>
+          {frontMatter.svgo?.pluginId && (
+            <div className={clsx(styles.extraTocEntries)}>
+              <a
+                href={`https://github.com/svg/svgo/blob/main/plugins/${frontMatter.svgo.pluginId}.js`}
+                target="_blank"
+                className={linkClassName ?? undefined}
+              >
+                <Translate>Read the implementation</Translate>
+              </a>
+            </div>
+          )}
+          <div className={clsx(styles.extraTocEntries)}>
+            <a
+              href={editUrl}
+              target="_blank"
+              className={linkClassName ?? undefined}
+            >
+              <Translate>Edit this page on GitHub</Translate>
+            </a>
+          </div>
         </div>
       )}
     </>

diff --git a/src/theme/TOCItems/index.module.css b/src/theme/TOCItems/index.module.css
@@ -11,8 +11,11 @@
   margin-left: -.6em;
 }
 
-.editPage {
-  font-size: .8em;
+.topBorder {
   border-top: solid 1px var(--ifm-toc-border-color);
+}
+
+.extraTocEntries {
+  font-size: .8em;
   padding-top: 1em;
 }