feat: terraform content split (#2228)

* feat: terraform content-spli

* chore: remove terraform submodule

* chore: NAV_DATA_DIRNAME + CONTENT_DIRNAME

* chore: update cdktf

* chore: temporarily disable pagesDirs pruning

* chore: update content-repo-preview script

* chore: update preview images

* chore: update error message

* add `remarkRewriteAssets`

* rename arg field to `getAssetPathParts`

* chore: update `start` to use `next dev`

* chore: remark-rewrite-assets logOnce

Author: thiskevinwang

content/cli

@@ -0,0 +1,49 @@
+import * as path from 'path'
+import visit from 'unist-util-visit'
+
+import type { Plugin } from 'unified'
+import type { Image } from 'mdast'
+
+/**
+ * This is a generator function that returns a remark plugin
+ * to rewrite asset urls in markdown files.
+ */
+export function remarkRewriteAssets(args: {
+  product: string
+  version: string
+  getAssetPathParts?: (nodeUrl: string) => string[]
+}): Plugin {
+  const { product, version, getAssetPathParts = (nodeUrl) => [nodeUrl] } = args
+
+  return function plugin() {
+    return function transform(tree) {
+      visit<Image>(tree, 'image', (node) => {
+        const originalUrl = node.url
+        const asset = path.posix.join(...getAssetPathParts(originalUrl))
+
+        const url = new URL('https://mktg-content-api.vercel.app/api/assets')
+        url.searchParams.append('asset', asset)
+        url.searchParams.append('version', version)
+        url.searchParams.append('product', product)
+
+        node.url = url.toString()
+        logOnce(
+          node.url,
+          `Rewriting asset url for local preview:
+- Found: ${originalUrl}
+- Replaced with: ${node.url}
+
+If this is a net-new asset, you'll need to commit and push it to GitHub.\n`
+        )
+      })
+    }
+  }
+}
+
+// A simple cache & util to prevent logging the same message multiple times
+const cache = new Map<string, boolean>()
+const logOnce = (id: string, message: string) => {
+  if (cache.get(id)) return
+  cache.set(id, true)
+  console.log(message)
+}

content/configuration

@@ -21,8 +21,10 @@ module.exports = withHashicorp({
     BUGSNAG_CLIENT_KEY: 'eab8d5350ab3b12d77b7498b23f9a89a',
     BUGSNAG_SERVER_KEY: '1f55a49019f70f94a17dd6d93210f09d',
     IS_CONTENT_PREVIEW: process.env.IS_CONTENT_PREVIEW || false,
-    NAV_DATA_PATH: process.env.NAV_DATA_PATH,
-    CONTENT_DIR: process.env.CONTENT_DIR,
+    PREVIEW_FROM_REPO: process.env.PREVIEW_FROM_REPO,
+    NAV_DATA_DIRNAME: process.env.NAV_DATA_DIRNAME || '',
+    CONTENT_DIRNAME: process.env.CONTENT_DIRNAME || '',
+    CURRENT_GIT_BRANCH: process.env.CURRENT_GIT_BRANCH || 'main',
   },
   images: {
     domains: ['www.datocms-assets.com'],

content/guides

@@ -80,7 +80,7 @@
     "generate:component": "next-hashicorp generate component",
     "generate:readme": "next-hashicorp markdown-blocks README.md",
     "lint": "next-hashicorp lint",
-    "start": "next-remote-watch './content/**/*.mdx'",
+    "start": "next dev",
     "static": "npm run build && npm run export",
     "linkcheck": "linkcheck <website url>"
   }

content/internals

@@ -3,13 +3,17 @@ import DocsPage from '@hashicorp/react-docs-page'
 import otherDocsData from 'data/other-docs-nav-data.json'
 // Imports below are only used server-side
 import { getStaticGenerationFunctions } from '@hashicorp/react-docs-page/server'
-import visit from 'unist-util-visit'
 import path from 'path'
 
+import { remarkRewriteAssets } from 'lib/remark-rewrite-assets'
+
 //  Configure the docs path
 const BASE_ROUTE = 'cdktf'
-const NAV_DATA = process.env.NAV_DATA_PATH || '../data/cdktf-nav-data.json'
-const CONTENT_DIR = process.env.CONTENT_DIR || '../docs/cdktf'
+const NAV_DATA = path.join(
+  process.env.NAV_DATA_DIRNAME,
+  BASE_ROUTE + '-nav-data.json'
+)
+const CONTENT_DIR = path.join(process.env.CONTENT_DIRNAME, BASE_ROUTE)
 const PRODUCT = { name: productName, slug: 'terraform-cdk' }
 
 export default function CDKLayout(props) {
@@ -27,7 +31,8 @@ export default function CDKLayout(props) {
 }
 
 const { getStaticPaths, getStaticProps } = getStaticGenerationFunctions(
-  process.env.IS_CONTENT_PREVIEW
+  process.env.IS_CONTENT_PREVIEW &&
+    process.env.PREVIEW_FROM_REPO === 'terraform-cdk'
     ? {
         strategy: 'fs',
         basePath: BASE_ROUTE,
@@ -40,30 +45,18 @@ const { getStaticPaths, getStaticProps } = getStaticGenerationFunctions(
           return `https://github.com/hashicorp/${PRODUCT.slug}/blob/main/website/${filepath}`
         },
         remarkPlugins: (params) => [
-          () => {
-            const product = PRODUCT.slug
-            const version = 'main'
-            return function transform(tree) {
-              visit(tree, 'image', (node) => {
-                const originalUrl = node.url
-                const assetPath = params.page
-                  ? path.posix.join(
-                      ...params.page,
-                      node.url.startsWith('.')
-                        ? `.${node.url}`
-                        : `../${node.url}`
-                    )
-                  : node.url
-                const asset = path.posix.join('website/docs/cdktf', assetPath)
-                node.url = `https://mktg-content-api.vercel.app/api/assets?product=${product}&version=${version}&asset=${asset}`
-                console.log(`Rewriting asset url for local preview:
-- Found: ${originalUrl}
-- Replaced with: ${node.url}
-
-If this is a net-new asset, it may not be available in the preview yet.`)
-              })
-            }
-          },
+          remarkRewriteAssets({
+            product: PRODUCT.slug,
+            version: process.env.CURRENT_GIT_BRANCH,
+            getAssetPathParts: (nodeUrl) =>
+              params.page
+                ? [
+                    'website/docs/cdktf',
+                    ...params.page,
+                    nodeUrl.startsWith('.') ? `.${nodeUrl}` : `../${nodeUrl}`,
+                  ]
+                : ['website/docs/cdktf', nodeUrl],
+          }),
         ],
       }
     : {

content/intro

@@ -2,15 +2,18 @@ import { productName, productSlug } from 'data/metadata'
 import DocsPage from '@hashicorp/react-docs-page'
 import otherDocsData from 'data/other-docs-nav-data.json'
 // Imports below are only used server-side
-import {
-  generateStaticPaths,
-  generateStaticProps,
-} from '@hashicorp/react-docs-page/server'
+import { getStaticGenerationFunctions } from '@hashicorp/react-docs-page/server'
+import path from 'path'
+
+import { remarkRewriteAssets } from 'lib/remark-rewrite-assets'
 
 //  Configure the docs path
 const BASE_ROUTE = 'cli'
-const NAV_DATA = 'data/cli-nav-data.json'
-const CONTENT_DIR = 'content/cli'
+const NAV_DATA = path.join(
+  process.env.NAV_DATA_DIRNAME,
+  BASE_ROUTE + '-nav-data.json'
+)
+const CONTENT_DIR = path.join(process.env.CONTENT_DIRNAME, BASE_ROUTE)
 const PRODUCT = { name: productName, slug: productSlug }
 
 export default function CLILayout(props) {
@@ -27,25 +30,33 @@ export default function CLILayout(props) {
   )
 }
 
-export async function getStaticPaths() {
-  const paths = await generateStaticPaths({
-    navDataFile: NAV_DATA,
-    localContentDir: CONTENT_DIR,
-    product: PRODUCT,
-  })
-  return { paths, fallback: false }
-}
+const { getStaticPaths, getStaticProps } = getStaticGenerationFunctions(
+  process.env.IS_CONTENT_PREVIEW &&
+    process.env.PREVIEW_FROM_REPO === 'terraform'
+    ? {
+        strategy: 'fs',
+        basePath: BASE_ROUTE,
+        localContentDir: CONTENT_DIR,
+        navDataFile: NAV_DATA,
+        product: PRODUCT.slug,
+        githubFileUrl(filepath) {
+          // This path rewriting is meant for local preview from `terraform`.
+          filepath = filepath.replace('preview/', '')
+          return `https://github.com/hashicorp/${PRODUCT.slug}/blob/main/website/${filepath}`
+        },
+        remarkPlugins: (params) => [
+          remarkRewriteAssets({
+            product: PRODUCT.slug,
+            version: process.env.CURRENT_GIT_BRANCH,
+            getAssetPathParts: (nodeUrl) => ['website', nodeUrl],
+          }),
+        ],
+      }
+    : {
+        strategy: 'remote',
+        basePath: BASE_ROUTE,
+        product: PRODUCT.slug,
+      }
+)
 
-export async function getStaticProps({ params }) {
-  const props = await generateStaticProps({
-    navDataFile: NAV_DATA,
-    localContentDir: CONTENT_DIR,
-    params,
-    product: PRODUCT,
-    githubFileUrl(path) {
-      const filepath = path.replace('content/', '')
-      return `https://github.com/hashicorp/${PRODUCT.slug}/blob/main/website/docs/${filepath}`
-    },
-  })
-  return { props }
-}
+export { getStaticPaths, getStaticProps }

content/language

@@ -1,15 +1,18 @@
 import { productName, productSlug } from 'data/metadata'
 import DocsPage from '@hashicorp/react-docs-page'
+import otherDocsData from 'data/other-docs-nav-data.json'
 // Imports below are only used server-side
-import {
-  generateStaticPaths,
-  generateStaticProps,
-} from '@hashicorp/react-docs-page/server'
+import { getStaticGenerationFunctions } from '@hashicorp/react-docs-page/server'
+import path from 'path'
+import { remarkRewriteAssets } from 'lib/remark-rewrite-assets'
 
 //  Configure the docs path
 const BASE_ROUTE = 'configuration'
-const NAV_DATA = 'data/configuration-nav-data.json'
-const CONTENT_DIR = 'content/configuration'
+const NAV_DATA = path.join(
+  process.env.NAV_DATA_DIRNAME,
+  BASE_ROUTE + '-nav-data.json'
+)
+const CONTENT_DIR = path.join(process.env.CONTENT_DIRNAME, BASE_ROUTE)
 const PRODUCT = { name: productName, slug: productSlug }
 
 export default function ConfigurationLayout(props) {
@@ -18,25 +21,33 @@ export default function ConfigurationLayout(props) {
   )
 }
 
-export async function getStaticPaths() {
-  const paths = await generateStaticPaths({
-    navDataFile: NAV_DATA,
-    localContentDir: CONTENT_DIR,
-    product: PRODUCT,
-  })
-  return { paths, fallback: false }
-}
+const { getStaticPaths, getStaticProps } = getStaticGenerationFunctions(
+  process.env.IS_CONTENT_PREVIEW &&
+    process.env.PREVIEW_FROM_REPO === 'terraform'
+    ? {
+        strategy: 'fs',
+        basePath: BASE_ROUTE,
+        localContentDir: CONTENT_DIR,
+        navDataFile: NAV_DATA,
+        product: PRODUCT.slug,
+        githubFileUrl(filepath) {
+          // This path rewriting is meant for local preview from `terraform`.
+          filepath = filepath.replace('preview/', '')
+          return `https://github.com/hashicorp/${PRODUCT.slug}/blob/main/website/${filepath}`
+        },
+        remarkPlugins: (params) => [
+          remarkRewriteAssets({
+            product: PRODUCT.slug,
+            version: process.env.CURRENT_GIT_BRANCH,
+            getAssetPathParts: (nodeUrl) => ['website', nodeUrl],
+          }),
+        ],
+      }
+    : {
+        strategy: 'remote',
+        basePath: BASE_ROUTE,
+        product: PRODUCT.slug,
+      }
+)
 
-export async function getStaticProps({ params }) {
-  const props = await generateStaticProps({
-    navDataFile: NAV_DATA,
-    localContentDir: CONTENT_DIR,
-    params,
-    product: PRODUCT,
-    githubFileUrl(path) {
-      const filepath = path.replace('content/', '')
-      return `https://github.com/hashicorp/${PRODUCT.slug}/blob/main/website/docs/${filepath}`
-    },
-  })
-  return { props }
-}
+export { getStaticPaths, getStaticProps }