feat(docs-page): support passing remarkPlugins as a fn (#524)

* support remarkPlugins as a fn

* fs-loader: remark plugin as func

Co-authored-by: Kevin Wang <kwangsan@gmail.com>

.changeset/tender-terms-mix.md

@@ -0,0 +1,5 @@
+---
+'@hashicorp/react-docs-page': minor
+---
+
+Support passing a function for remarkPlugins, which accepts the params for the current page being rendered.

packages/docs-page/server/index.ts

@@ -26,7 +26,8 @@ export function getStaticGenerationFunctions(
     | ({
         basePath: string
         strategy: 'remote'
-      } & BaseOpts)
+      } & BaseOpts &
+        Partial<ConstructorParameters<typeof RemoteContentLoader>[0]>)
     | ({
         localContentDir: string
         navDataFile: string
@@ -36,7 +37,8 @@ export function getStaticGenerationFunctions(
          * Passed to our resolveIncludes plugin.
          * Defaults to "content/partials". */
         localPartialsDir?: string
-      } & BaseOpts)
+      } & BaseOpts &
+        Partial<ConstructorParameters<typeof FileSystemLoader>[0]>)
 ): {
   getStaticPaths: GetStaticPaths
   getStaticProps: GetStaticProps

packages/docs-page/server/loaders/file-system.ts

@@ -1,3 +1,4 @@
+import type { ParsedUrlQuery } from 'querystring'
 import path from 'path'
 import fs from 'fs'
 import { GetStaticPropsContext } from 'next'
@@ -16,7 +17,7 @@ interface FileSystemLoaderOpts extends DataLoaderOpts {
   navDataFile: string
   localContentDir: string
   mainBranch?: string // = 'main',
-  remarkPlugins?: $TSFixMe[]
+  remarkPlugins?: ((params?: ParsedUrlQuery) => $TSFixMe[]) | $TSFixMe[]
   scope?: Record<string, $TSFixMe>
   localPartialsDir?: string
   githubFileUrl?: (path: string) => string
@@ -41,9 +42,21 @@ export default class FileSystemLoader implements DataLoader {
   loadStaticProps = async ({
     params,
   }: GetStaticPropsContext): Promise<$TSFixMe> => {
+    let remarkPlugins: $TSFixMe[] = []
+
+    // We support passing in a function to remarkPlugins, which gets the parameters of the current page
+    if (typeof this.opts.remarkPlugins === 'function') {
+      remarkPlugins = this.opts.remarkPlugins(params)
+      if (!Array.isArray(remarkPlugins)) {
+        throw new Error(
+          '`remarkPlugins:` When specified as a function, must return an array of remark plugins'
+        )
+      }
+    }
+
     const mdxRenderer = (mdx) =>
       renderPageMdx(mdx, {
-        remarkPlugins: this.opts.remarkPlugins,
+        remarkPlugins,
         scope: this.opts.scope,
         localPartialsDir: this.opts.localPartialsDir,
       })

packages/docs-page/server/loaders/remote-content.ts

@@ -1,3 +1,4 @@
+import type { ParsedUrlQuery } from 'querystring'
 import moize, { Options } from 'moize'
 import semver from 'semver'
 import { GetStaticPropsContext } from 'next'
@@ -17,7 +18,7 @@ import { getPathsFromNavData } from '../get-paths-from-nav-data'
 interface RemoteContentLoaderOpts extends DataLoaderOpts {
   basePath: string
   enabledVersionedDocs?: boolean
-  remarkPlugins?: $TSFixMe[]
+  remarkPlugins?: ((params?: ParsedUrlQuery) => $TSFixMe[]) | $TSFixMe[]
   mainBranch?: string // = 'main',
   scope?: Record<string, $TSFixMe>
 }
@@ -114,9 +115,21 @@ export default class RemoteContentLoader implements DataLoader {
         ? (params[this.opts.paramId] as string[]).join('/')
         : ''
 
+    let remarkPlugins: $TSFixMe[] = []
+
+    // We support passing in a function to remarkPlugins, which gets the parameters of the current page
+    if (typeof this.opts.remarkPlugins === 'function') {
+      remarkPlugins = this.opts.remarkPlugins(params)
+      if (!Array.isArray(remarkPlugins)) {
+        throw new Error(
+          '`remarkPlugins:` When specified as a function, must return an array of remark plugins'
+        )
+      }
+    }
+
     const mdxRenderer = (mdx) =>
       renderPageMdx(mdx, {
-        remarkPlugins: this.opts.remarkPlugins,
+        remarkPlugins,
         scope: this.opts.scope,
       })
 
@@ -125,9 +138,8 @@ export default class RemoteContentLoader implements DataLoader {
       params![this.opts.paramId!] as string[]
     )
 
-    const versionMetadataList: VersionMetadataItem[] = await cachedFetchVersionMetadataList(
-      this.opts.product
-    )
+    const versionMetadataList: VersionMetadataItem[] =
+      await cachedFetchVersionMetadataList(this.opts.product)
     // remove trailing index to ensure we fetch the right document from the DB
     const pathParamsNoIndex = paramsNoVersion.filter(
       (param, idx, arr) => !(param === 'index' && idx === arr.length - 1)