From c929c055df86b20e88bc0f302a18a5c3548684ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis=20Pr=C3=A9?= Date: Mon, 20 Apr 2026 16:24:34 -0700 Subject: [PATCH 1/2] Centralize codegen path configuration Add codegen/lib/config.ts as single source of truth for all paths: - apiReferenceRoot: site section root from repo root ('docs/api-reference') - guidesRoot: guides site section root ('docs/guides') - apiUrlPrefix: published URL prefix ('/api') - baseUrl, siteUrlPrefix: docs site URL constants Change Metalsmith destination from '../docs' to '../' (repo root) so file keys match the full path from repo root (docs/api-reference/...). Rename source directory from codegen/docs/ to codegen/source/ to avoid confusion with the output docs/ directory. Co-Authored-By: Claude Opus 4.6 (1M context) --- codegen/lib/config.ts | 17 +++++++++++++++++ codegen/lib/postprocess.ts | 18 ++++++++++-------- codegen/lib/reference.ts | 3 ++- codegen/lib/report.ts | 6 ++++-- codegen/lib/summary.ts | 15 +++++++-------- codegen/smith.ts | 11 ++++++----- .../{ => source}/docs/api-reference/README.md | 0 .../docs/api-reference/authentication.md | 0 .../docs/api-reference/installation.md | 0 .../docs/api-reference/pagination.md | 0 10 files changed, 46 insertions(+), 24 deletions(-) create mode 100644 codegen/lib/config.ts rename codegen/{ => source}/docs/api-reference/README.md (100%) rename codegen/{ => source}/docs/api-reference/authentication.md (100%) rename codegen/{ => source}/docs/api-reference/installation.md (100%) rename codegen/{ => source}/docs/api-reference/pagination.md (100%) diff --git a/codegen/lib/config.ts b/codegen/lib/config.ts new file mode 100644 index 000000000..ead81a04e --- /dev/null +++ b/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') diff --git a/codegen/lib/postprocess.ts b/codegen/lib/postprocess.ts index e8f20ac38..3e215422a 100644 --- a/codegen/lib/postprocess.ts +++ b/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` diff --git a/codegen/lib/reference.ts b/codegen/lib/reference.ts index 8c2587448..58e4725af 100644 --- a/codegen/lib/reference.ts +++ b/codegen/lib/reference.ts @@ -15,6 +15,7 @@ import { type ApiSummaryLayoutContext, setSummaryLayoutContext, } from './layout/summary.js' +import { apiReferenceRoot } from './config.js' import { PathMetadataSchema } from './path-metadata.js' interface Metadata { @@ -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 = ( diff --git a/codegen/lib/report.ts b/codegen/lib/report.ts index 8365ec24f..304088aa1 100644 --- a/codegen/lib/report.ts +++ b/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', } diff --git a/codegen/lib/summary.ts b/codegen/lib/summary.ts index 624e45d0f..73cc874ca 100644 --- a/codegen/lib/summary.ts +++ b/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 => { - 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 => { - const buf = await readFile(summaryPath) + const buf = await readFile(apiReferenceSummaryPath) return buf.toString('utf-8') } diff --git a/codegen/smith.ts b/codegen/smith.ts index 7b01bcb8d..7b85a04e6 100644 --- a/codegen/smith.ts +++ b/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({ diff --git a/codegen/docs/api-reference/README.md b/codegen/source/docs/api-reference/README.md similarity index 100% rename from codegen/docs/api-reference/README.md rename to codegen/source/docs/api-reference/README.md diff --git a/codegen/docs/api-reference/authentication.md b/codegen/source/docs/api-reference/authentication.md similarity index 100% rename from codegen/docs/api-reference/authentication.md rename to codegen/source/docs/api-reference/authentication.md diff --git a/codegen/docs/api-reference/installation.md b/codegen/source/docs/api-reference/installation.md similarity index 100% rename from codegen/docs/api-reference/installation.md rename to codegen/source/docs/api-reference/installation.md diff --git a/codegen/docs/api-reference/pagination.md b/codegen/source/docs/api-reference/pagination.md similarity index 100% rename from codegen/docs/api-reference/pagination.md rename to codegen/source/docs/api-reference/pagination.md From 542ca1354f5ce6f4afc41ccb3dbbd070340cf0b0 Mon Sep 17 00:00:00 2001 From: Seam Bot Date: Mon, 20 Apr 2026 23:43:06 +0000 Subject: [PATCH 2/2] ci: Format code --- codegen/lib/reference.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/codegen/lib/reference.ts b/codegen/lib/reference.ts index 58e4725af..87299c666 100644 --- a/codegen/lib/reference.ts +++ b/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, @@ -15,7 +16,6 @@ import { type ApiSummaryLayoutContext, setSummaryLayoutContext, } from './layout/summary.js' -import { apiReferenceRoot } from './config.js' import { PathMetadataSchema } from './path-metadata.js' interface Metadata {