Centralize codegen path configuration

codegen/lib/config.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path'
+
+// Site section roots (paths from repo root)
+export const apiReferenceRoot = join('docs', 'api-reference')
+export const guidesRoot = join('docs', 'guides')
+
+// The published URL prefix for the API Reference site section on docs.seam.co.
+export const apiReferenceUrlPrefix = '/api'
+
+// The base URL for the published documentation site.
+export const baseUrl = 'https://docs.seam.co/latest/'
+
+// The URL prefix to strip when resolving absolute URLs to file paths.
+export const siteUrlPrefix = '/latest'
+
+// Derived paths
+export const apiReferenceSummaryPath = join(apiReferenceRoot, 'SUMMARY.md')

codegen/lib/postprocess.ts

@@ -3,10 +3,12 @@ import { dirname, join, relative, sep } from 'node:path'
 
 import type Metalsmith from 'metalsmith'
 
-const baseUrl = 'https://docs.seam.co/latest/'
-const urlPrefix = '/latest'
-const apiUrlPrefix = '/api'
-const apiReferenceRoot = join('docs', 'api-reference')
+import {
+  apiReferenceRoot,
+  apiReferenceUrlPrefix,
+  baseUrl,
+  siteUrlPrefix,
+} from './config.js'
 
 export const postprocess = (
   files: Metalsmith.Files,
@@ -18,13 +20,13 @@ export const postprocess = (
       contents.replaceAll(new RegExp(`(${baseUrl}[^)]+)`, 'g'), ($1, $2) => {
         if (typeof $2 !== 'string') return $1
         const url = new URL($2)
-        url.pathname = url.pathname.replace(urlPrefix, '')
+        url.pathname = url.pathname.replace(siteUrlPrefix, '')
 
         // Only relativize links to pages within the api-reference space.
-        // The site section uses /api as its URL prefix.
+        // The site section uses apiReferenceUrlPrefix as its URL prefix.
         // Cross-section links (to guides) stay as absolute URLs.
-        if (!url.pathname.startsWith(apiUrlPrefix + '/')) return $1
-        const apiPath = url.pathname.replace(apiUrlPrefix, '')
+        if (!url.pathname.startsWith(apiReferenceUrlPrefix + '/')) return $1
+        const apiPath = url.pathname.replace(apiReferenceUrlPrefix, '')
         const targetRoot = join(apiReferenceRoot, apiPath)
 
         const target = `${targetRoot}.md`

codegen/lib/reference.ts

@@ -3,6 +3,7 @@ import type Metalsmith from 'metalsmith'
 
 import { toCapitalCase } from 'lib/handlebars/helpers.js'
 
+import { apiReferenceRoot } from './config.js'
 import {
   type ApiEndpointLayoutContext,
   type ApiNamespaceLayoutContext,
@@ -27,7 +28,7 @@ type File = ApiEndpointLayoutContext &
   ApiNamespaceLayoutContext &
   ApiSummaryLayoutContext & { layout: string }
 
-const rootPath = 'api-reference'
+const rootPath = apiReferenceRoot
 const indexFile = 'README.md'
 
 export const reference = (

codegen/lib/report.ts

@@ -12,6 +12,8 @@ import type {
 import { openapi } from '@seamapi/types/connect'
 import type Metalsmith from 'metalsmith'
 
+import { apiReferenceRoot } from './config.js'
+
 const defaultDeprecatedMessage = 'No deprecated message provided'
 const defaultDraftMessage = 'No draft message provided'
 const defaultUndocumentedMessage = 'No undocumented message provided'
@@ -75,13 +77,13 @@ export const report = (
 
   const reportData = generateReport(metadata)
 
-  files['api-reference/_report.md'] = {
+  files[`${apiReferenceRoot}/_report.md`] = {
     contents: Buffer.from('\n'),
     layout: 'report.hbs',
     ...reportData,
   }
 
-  files['api-reference/_blueprint.json'] = {
+  files[`${apiReferenceRoot}/_blueprint.json`] = {
     contents: Buffer.from(JSON.stringify(metadata.blueprint, null, 2)),
     layout: 'default.hbs',
   }

codegen/lib/summary.ts

@@ -1,29 +1,28 @@
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
 
 import type Metalsmith from 'metalsmith'
 
-const summaryPath = join('docs', 'api-reference', 'SUMMARY.md')
+import { apiReferenceRoot, apiReferenceSummaryPath } from './config.js'
 
 export const summary = async (
   files: Metalsmith.Files,
   _metalsmith: Metalsmith,
 ): Promise<void> => {
-  const apiSummary =
-    files['api-reference/_summary.md']?.contents?.toString('utf-8')
+  const summaryKey = `${apiReferenceRoot}/_summary.md`
+  const apiSummary = files[summaryKey]?.contents?.toString('utf-8')
   if (apiSummary == null) {
-    throw new Error('Missing api-reference/_summary.md')
+    throw new Error(`Missing ${summaryKey}`)
   }
 
-  const k = 'api-reference/SUMMARY.md'
+  const k = `${apiReferenceRoot}/SUMMARY.md`
   const summary = await readSummary()
   const contents = getUpdatedSummary(summary, apiSummary)
   files[k] = { contents: Buffer.from(`${contents}\n`) }
-  delete files['api-reference/_summary.md']
+  delete files[summaryKey]
 }
 
 const readSummary = async (): Promise<string> => {
-  const buf = await readFile(summaryPath)
+  const buf = await readFile(apiReferenceSummaryPath)
   return buf.toString('utf-8')
 }
 

codegen/smith.ts

@@ -9,6 +9,7 @@ import * as types from '@seamapi/types/connect'
 import { deleteAsync } from 'del'
 import Metalsmith from 'metalsmith'
 
+import { apiReferenceRoot } from './lib/config.js'
 import {
   formatCode,
   helpers,
@@ -22,17 +23,17 @@ const rootDir = dirname(fileURLToPath(import.meta.url))
 
 await Promise.all([
   deleteAsync([
-    './docs/api-reference/**',
-    '!./docs/api-reference/SUMMARY.md',
-    '!./docs/api-reference/.gitbook.yaml',
+    `./${apiReferenceRoot}/**`,
+    `!./${apiReferenceRoot}/SUMMARY.md`,
+    `!./${apiReferenceRoot}/.gitbook.yaml`,
   ]),
 ])
 
 const partials = await getHandlebarsPartials(`${rootDir}/layouts/partials`)
 
 Metalsmith(rootDir)
-  .source('./docs')
-  .destination('../docs')
+  .source('./source')
+  .destination('../')
   .clean(false)
   .use(
     metadata({