From 9568d09c1ddd0bf5195ca2af243917169e97b1aa Mon Sep 17 00:00:00 2001 From: Nick Chisiu <8492343+nickchisiu@users.noreply.github.com> Date: Sat, 12 Sep 2026 11:59:01 +0300 Subject: [PATCH 1/2] refactor: remove DocsStartCommand and update documentation build process - Removed the DocsStartCommand from the CLI, simplifying the documentation commands. - Updated the DocsBuildCommand to export static HTML documentation instead of a Node.js server. - Modified related documentation to reflect the changes in the build process and deployment instructions. - Enhanced error handling and logging for the build process. - Adjusted the UI components for better responsiveness and user experience. - Cleaned up unused code and dependencies related to the removed start command. --- CHANGELOG.md | 8 +- DEVELOPMENT.md | 21 +++- README.md | 14 +-- RELEASING.md | 4 +- e2e/docs-ui-static.spec.ts | 45 ++++++-- packages/cli/README.md | 9 ++ packages/cli/__tests__/docs-build.test.ts | 104 ++++++++++++++++++ packages/cli/src/app.module.ts | 2 - .../cli/src/commands/docs/build.command.ts | 82 +++++--------- .../cli/src/commands/docs/docs.command.ts | 3 +- .../cli/src/commands/docs/start.command.ts | 102 ----------------- packages/docs-site/docs/api-docs.md | 10 +- packages/docs-site/docs/quickstart.md | 18 ++- packages/docs-ui/README.md | 6 +- packages/docs-ui/app/api/docs-watch/route.ts | 6 +- packages/docs-ui/app/docs/[slug]/page.tsx | 2 +- packages/docs-ui/app/docs/docs-shell.tsx | 87 ++++++++++----- .../docs-ui/components/docs/docs-header.tsx | 35 +++--- .../docs-ui/components/docs/mcp-reference.tsx | 54 +++++---- .../components/docs/mcp-setup-guide.tsx | 8 +- packages/docs-ui/lib/use-project-watch.ts | 2 +- packages/docs-ui/next.config.js | 18 ++- packages/docs-ui/scripts/cloudflare.mjs | 1 - scripts/publish-cli.mjs | 2 + scripts/smoke-cli-package.mjs | 53 +++++---- 25 files changed, 381 insertions(+), 315 deletions(-) create mode 100644 packages/cli/__tests__/docs-build.test.ts delete mode 100644 packages/cli/src/commands/docs/start.command.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ce3b0b..f7bc791 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,15 +8,17 @@ The project uses Semantic Versioning. Each release contains the same three chang ### New Features -- None. +- `cortex docs build` now exports static HTML, CSS, JavaScript, and documentation data for deployment to a static web host. ### Bug Fixes -- None. +- Fixed the documentation layout and navigation on mobile screens. +- Fixed MCP tool links that scrolled to the wrong position after the setup guide loaded. +- Excluded workspace test dependencies from the CLI release package to prevent dependency conflicts during CI packaging. ### Improvements -- None. +- Removed `cortex docs start`. Use `cortex docs serve` for a local preview with file watching. Host production output as static files without a Node.js server. ## [0.1.29] - 2026-08-31 diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0219e6a..3e9d13e 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -129,10 +129,10 @@ npm run --workspace=@cortex-docs/docs-ui dev:next ### Cloudflare demo -The public demo uses two Cloudflare Workers: +The public demo uses a Worker for the API and static hosting for the documentation: - `api.demo.cortexdocs.dev` serves the REST, GraphQL, WebSocket, OpenRPC, and HTTP bridge endpoints. -- `demo.cortexdocs.dev` serves the Next.js documentation UI through OpenNext. +- `demo.cortexdocs.dev` serves the exported documentation through Cloudflare Static Assets. Run the API Worker without the docs UI: @@ -140,13 +140,13 @@ Run the API Worker without the docs UI: npm run --workspace=@cortex-docs/demo-api dev ``` -Build the docs UI for the Cloudflare runtime: +Build the static documentation for Cloudflare: ```bash npm run --workspace=@cortex-docs/docs-ui demo:build ``` -Preview the complete docs UI Worker locally: +Preview the static documentation locally: ```bash npm run --workspace=@cortex-docs/docs-ui demo:preview @@ -344,7 +344,18 @@ The spec is served via the `/api/spec` route, which reads the file path from the npm run --workspace=@cortex-docs/docs-site dev ``` -Starts the product documentation site locally on `:3200` with hot reload. Edit a Markdown file in `packages/docs-site/docs/` to update a page. +The command starts the product documentation site locally on `:3200` with hot reload. Edit a Markdown file in `packages/docs-site/docs/` to update a page. + +Build the product documentation as static files: + +```bash +npm run --workspace=@cortex-docs/docs-site build +``` + +This command runs `cortex docs build --output .cortex/docs` in the product docs workspace. The output directory is `packages/docs-site/.cortex/docs`. + +Deploy the output directory to a static web host. Configure page URLs such as `/docs/quickstart` to resolve to `/docs/quickstart.html`. +The deployed site needs no Node.js server or access to the original configuration and specifications. Rebuild the site after source changes. ## Modifying the Docs Site diff --git a/README.md b/README.md index 3917ad7..dbcf22d 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ mcp-server → generated/mcp-server The generated MCP server gives AI agents typed tools, specifications, SDK guides, and project documentation. -Generate the files. Then start the documentation server: +Generate the files. Then start the local documentation preview: ```bash cortex generate @@ -82,7 +82,7 @@ Open `http://localhost:3012`. Press `Ctrl+C` to stop the server. - Generate SDKs for TypeScript, Python, Go, Java, Kotlin, Ruby, PHP, C#, Rust, C++, and C. - Combine multiple specification files in one generated SDK. - Generate HTTP, WebSocket, GraphQL, gRPC, and JSON-RPC clients. -- Generate a production documentation server with interactive API reference pages. +- Build static HTML documentation with interactive API reference pages. - Generate an MCP server with typed tools, embedded specifications, SDK guides, and project documentation for AI agents. - Add Markdown pages, SDK guides, and all API specifications to the MCP server. - Customize generated output with sparse Eta template overrides. @@ -184,8 +184,7 @@ See the [configuration reference](packages/docs-site/docs/configuration.md) for | `cortex generate --language typescript` | Generate one configured language. | | `cortex generate --dry-run` | Show planned output without writing files. | | `cortex docs serve` | Start the development server and watch project files. | -| `cortex docs build --output .cortex/docs` | Create a production Node.js documentation build. | -| `cortex docs start --output .cortex/docs` | Start a production documentation build. | +| `cortex docs build --output .cortex/docs` | Build static HTML documentation. | | `cortex mcp generate` | Generate only the MCP server. | | `cortex publish --dry-run` | Check package publication without uploading. | | `cortex publish` | Publish enabled generated packages. | @@ -204,14 +203,15 @@ The generated MCP server does not call gRPC methods. It exposes Protocol Buffer ## Production documentation -The build command creates a self-contained Next.js server. It is not a static HTML export. +The build command exports the documentation as static HTML, CSS, JavaScript, and data files. ```bash cortex docs build --output .cortex/docs -NODE_ENV=production cortex docs start --output .cortex/docs --port 3000 ``` -Deploy the output directory to a service that can run Node.js. Keep `cortex.config.yml` and its referenced specifications available at runtime. +Deploy the output directory to a static web host. Configure the host to resolve page URLs such as `/docs/quickstart` to `/docs/quickstart.html`. + +The deployed site needs no Node.js server or access to the original configuration and specifications. Rebuild the site after source changes. Use `cortex docs serve` for a local preview with file watching. ## MCP output diff --git a/RELEASING.md b/RELEASING.md index d2f49fb..cd4eefa 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -114,13 +114,13 @@ Run this command to calculate the next version without file changes: node scripts/set-release-version.mjs --check ``` -Run this command to build the demo for the Cloudflare runtime: +Run this command to build the demo documentation as static files for Cloudflare: ```bash npm run --workspace=@cortex-docs/docs-ui demo:build ``` -Run this command to build the product docs for the Cloudflare runtime: +Run this command to build the product documentation as static files for Cloudflare: ```bash npm run --workspace=@cortex-docs/docs-ui docs:build diff --git a/e2e/docs-ui-static.spec.ts b/e2e/docs-ui-static.spec.ts index fac8b6d..0f459d2 100644 --- a/e2e/docs-ui-static.spec.ts +++ b/e2e/docs-ui-static.spec.ts @@ -38,18 +38,49 @@ test.describe('Cloudflare Static Assets export', () => { }); test('serves generated MCP and SDK deep links', async ({ page }) => { - await page.goto('/mcp/docs_quickstart'); - await expect(page.getByText('docs_quickstart').first()).toBeVisible(); - - await page.goto('/mcp/sdk_typescript_petstore_typescript_client_sdk'); - await expect( - page.getByText('sdk_typescript_petstore_typescript_client_sdk').first(), - ).toBeVisible(); + const mcp = await (await page.request.get('/api/mcp')).json(); + for (const tool of [ + 'docs_quickstart', + 'sdk_typescript_petstore_typescript_client_sdk', + mcp.tools.at(-1).name, + ]) { + await page.goto(`/mcp/${tool}`); + await page.waitForLoadState('networkidle'); + await expect(page.locator(`[id="mcp-${tool}"]`)).toBeInViewport({ ratio: 1 }); + await expect(page.getByRole('navigation', { name: 'breadcrumb' })).toContainText(tool); + await expect(page).toHaveURL(new RegExp(`/mcp/${tool}$`)); + } await page.goto('/sdks/typescript'); await expect(page.getByText('TypeScript').first()).toBeVisible(); }); + for (const width of [320, 390]) { + test(`keeps documentation readable and navigation usable at ${width}px`, async ({ page }) => { + await page.setViewportSize({ width, height: 844 }); + await page.goto('/docs/quickstart'); + await expect(page.getByRole('heading', { name: 'Quickstart', exact: true })).toBeVisible(); + const article = await page.locator('article').boundingBox(); + expect(article?.width).toBeGreaterThanOrEqual(width - 40); + expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBe(width); + await expect(page.getByRole('button', { name: 'Toggle theme' })).toBeInViewport({ ratio: 1 }); + await expect(page.getByRole('button', { name: 'Search documentation' })).toBeInViewport({ + ratio: 1, + }); + + await page.getByRole('button', { name: 'Open documentation navigation' }).click(); + const navigation = page.getByRole('dialog', { name: 'Documentation', exact: true }); + await expect(navigation).toBeVisible(); + await navigation.getByRole('link', { name: 'Quickstart', exact: true }).click(); + await expect(navigation).not.toBeVisible(); + + await page.getByRole('button', { name: 'Search documentation' }).click(); + await expect(page.getByRole('dialog')).toBeVisible(); + await page.keyboard.press('Escape'); + await expect(page.getByRole('dialog')).not.toBeVisible(); + }); + } + test('matches the local demo documentation and MCP SDK tools', async ({ request }) => { const docsResponse = await request.get('/api/docs'); const docs = await docsResponse.json(); diff --git a/packages/cli/README.md b/packages/cli/README.md index d6a1aae..db6715c 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -17,4 +17,13 @@ cortex generate cortex docs serve ``` +Build static HTML documentation for deployment: + +```bash +cortex docs build --output .cortex/docs +``` + +Deploy the output directory to a static web host. Configure page URLs such as `/docs/quickstart` to resolve to `/docs/quickstart.html`. +The deployed site needs no Node.js server. Rebuild the site after source changes. + Read the [Cortex Docs repository](https://github.com/cortex-docs/cortex) for the complete documentation. diff --git a/packages/cli/__tests__/docs-build.test.ts b/packages/cli/__tests__/docs-build.test.ts new file mode 100644 index 0000000..4edec19 --- /dev/null +++ b/packages/cli/__tests__/docs-build.test.ts @@ -0,0 +1,104 @@ +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { execFileSync } from 'node:child_process'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { DocsBuildCommand } from '../src/commands/docs/build.command'; +import { prepareDocsUiBuildRuntime, resolveDocsUiPath } from '../src/commands/docs/runtime'; +import type { LoggerService } from '../src/services/logger.service'; +import type { ProjectService } from '../src/services/project.service'; + +vi.mock('node:child_process', () => ({ execFileSync: vi.fn() })); +vi.mock('../src/commands/docs/runtime', () => ({ + prepareDocsUiBuildRuntime: vi.fn(), + resolveDocsUiPath: vi.fn(), + resolveNextBin: () => '/next/bin/next', +})); + +describe('docs build', () => { + let workspace: string; + let outputDir: string; + let command: DocsBuildCommand; + + beforeEach(() => { + vi.clearAllMocks(); + workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'cortex-docs-build-')); + outputDir = path.join(workspace, 'site'); + vi.mocked(resolveDocsUiPath).mockReturnValue(workspace); + command = new DocsBuildCommand( + { header: vi.fn(), info: vi.fn(), success: vi.fn() } as unknown as LoggerService, + { + findConfig: async () => path.join(workspace, 'cortex.config.yml'), + loadConfig: async () => ({ project: 'test', sources: [] }), + } as unknown as ProjectService, + ); + fs.mkdirSync(outputDir); + fs.writeFileSync(path.join(outputDir, 'old.html'), 'previous build'); + }); + + afterEach(() => { + fs.rmSync(workspace, { recursive: true, force: true }); + }); + + it('replaces the previous build with exported pages, data, and browser assets', async () => { + vi.mocked(execFileSync).mockImplementation((_file, _args, options) => { + const runtimeDir = String(options!.cwd); + expect(options!.env).toMatchObject({ + CORTEX_STATIC_EXPORT: '1', + CORTEX_DIST_DIR: '.next', + CORTEX_CONFIG_PATH: path.join(workspace, 'cortex.config.yml'), + }); + for (const [name, content] of [ + ['out/index.html', '

Docs

'], + ['out/docs/guide.html', '

Guide

'], + ['out/api/config', '{"project":"test"}'], + ['out/_next/static/app.js', 'browser code'], + ['out/logo.svg', ''], + ['.next/server/app.js', 'server code'], + ]) { + const file = path.join(runtimeDir, name); + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, content); + } + return Buffer.from(''); + }); + + await command.run([], { output: outputDir }); + + expect(fs.readFileSync(path.join(outputDir, 'index.html'), 'utf8')).toContain('Docs'); + expect(fs.readFileSync(path.join(outputDir, 'docs/guide.html'), 'utf8')).toContain('Guide'); + expect(JSON.parse(fs.readFileSync(path.join(outputDir, 'api/config'), 'utf8'))).toEqual({ + project: 'test', + }); + expect(fs.existsSync(path.join(outputDir, '_next/static/app.js'))).toBe(true); + expect(fs.existsSync(path.join(outputDir, 'logo.svg'))).toBe(true); + for (const file of ['old.html', '.next', '.cortex-docs-build.json', 'server.js']) { + expect(fs.existsSync(path.join(outputDir, file))).toBe(false); + } + expect(fs.readdirSync(workspace).filter((name) => name.startsWith('.cortex-build-'))).toEqual( + [], + ); + }); + + it.each(['prepare', 'compile', 'export'])( + 'preserves the previous build after a %s failure', + async (stage) => { + if (stage === 'prepare') { + vi.mocked(prepareDocsUiBuildRuntime).mockImplementationOnce(() => { + throw new Error('Cannot prepare runtime'); + }); + } + vi.mocked(execFileSync).mockImplementation(() => { + if (stage === 'compile') throw new Error('Compilation failed'); + return Buffer.from(''); + }); + + await expect(command.run([], { output: outputDir })).rejects.toThrow(); + + expect(fs.readFileSync(path.join(outputDir, 'old.html'), 'utf8')).toBe('previous build'); + expect(fs.readdirSync(workspace).filter((name) => name.startsWith('.cortex-build-'))).toEqual( + [], + ); + }, + ); +}); diff --git a/packages/cli/src/app.module.ts b/packages/cli/src/app.module.ts index f3d091a..3a0982a 100644 --- a/packages/cli/src/app.module.ts +++ b/packages/cli/src/app.module.ts @@ -5,7 +5,6 @@ import { ValidateCommand } from './commands/validate/validate.command'; import { DocsCommand } from './commands/docs/docs.command'; import { DocsServeCommand } from './commands/docs/serve.command'; import { DocsBuildCommand } from './commands/docs/build.command'; -import { DocsStartCommand } from './commands/docs/start.command'; import { McpCommand } from './commands/mcp/mcp.command'; import { McpGenerateCommand } from './commands/mcp/mcp-generate.command'; import { PublishCommand } from './commands/publish/publish.command'; @@ -22,7 +21,6 @@ import { LoggerService } from './services/logger.service'; DocsCommand, DocsServeCommand, DocsBuildCommand, - DocsStartCommand, McpCommand, McpGenerateCommand, PublishCommand, diff --git a/packages/cli/src/commands/docs/build.command.ts b/packages/cli/src/commands/docs/build.command.ts index 67b7c82..badc2ee 100644 --- a/packages/cli/src/commands/docs/build.command.ts +++ b/packages/cli/src/commands/docs/build.command.ts @@ -14,7 +14,7 @@ import { prepareDocsUiBuildRuntime, resolveDocsUiPath, resolveNextBin } from './ @SubCommand({ name: 'build', - description: 'Build production API documentation', + description: 'Build static HTML API documentation', }) export class DocsBuildCommand extends CommandRunner { constructor( @@ -29,7 +29,7 @@ export class DocsBuildCommand extends CommandRunner { const foundConfigPath = await this.project.findConfig(); const configPath = foundConfigPath ? path.resolve(foundConfigPath) : undefined; - const config = await this.project.loadConfig(); + const config = await this.project.loadConfig(configPath); const templateRoot = resolveGeneratorTemplateRoot(config, configPath); assertTemplateRoot(templateRoot); const languageTemplateDirs = getAllLanguageTemplateDirs(config, configPath); @@ -54,58 +54,53 @@ export class DocsBuildCommand extends CommandRunner { const { execFileSync } = await import('node:child_process'); const runtimeDir = fs.mkdtempSync(path.join(docsUiPath, '.cortex-build-')); - prepareDocsUiBuildRuntime(docsUiPath, runtimeDir); - const distDir = '.next'; - const buildDir = path.join(runtimeDir, distDir); + const exportDir = path.join(runtimeDir, 'out'); const env: Record = { ...(process.env as Record), - CORTEX_DIST_DIR: distDir, + CORTEX_DIST_DIR: '.next', CORTEX_DOCS_UI_ROOT: docsUiPath, - CORTEX_STANDALONE_BUILD: '1', + CORTEX_STATIC_EXPORT: '1', + CORTEX_CLOUDFLARE: '0', }; if (configPath) env.CORTEX_CONFIG_PATH = configPath; if (specPath) env.CORTEX_SPEC_PATH = specPath; + const asyncApiPath = getFirstSpecPath(config, 'asyncapi-spec'); + if (asyncApiPath) env.CORTEX_ASYNCAPI_PATH = asyncApiPath; + const graphqlPath = getFirstSpecPath(config, 'graphql-spec'); + if (graphqlPath) env.CORTEX_GRAPHQL_PATH = graphqlPath; + const grpcPath = getFirstSpecPath(config, 'grpc-spec'); + if (grpcPath) env.CORTEX_GRPC_PATH = grpcPath; + const openRpcPath = getFirstSpecPath(config, 'openrpc-spec'); + if (openRpcPath) env.CORTEX_OPENRPC_PATH = openRpcPath; + if (config.logo) env.CORTEX_LOGO_PATH = config.logo; + if (config.favicon) env.CORTEX_FAVICON_PATH = config.favicon; if (templateRoot) env.CORTEX_TEMPLATE_ROOT = templateRoot; + if (languageTemplateDirs.length > 0) { + env.CORTEX_LANGUAGE_TEMPLATE_DIRS = JSON.stringify(languageTemplateDirs); + } - this.logger.info('Building docs...'); + this.logger.info('Building static docs...'); try { + prepareDocsUiBuildRuntime(docsUiPath, runtimeDir); execFileSync(process.execPath, [nextBin, 'build', '--webpack'], { cwd: runtimeDir, env, stdio: 'inherit', }); - const standaloneRoot = path.join(buildDir, 'standalone'); - const serverPath = this.findStandaloneServer(standaloneRoot); - if (!serverPath) throw new Error('The Next.js standalone build did not contain server.js.'); + if (!fs.existsSync(path.join(exportDir, 'index.html'))) { + throw new Error('The static documentation build did not contain index.html.'); + } fs.rmSync(outputDir, { recursive: true, force: true }); - fs.mkdirSync(outputDir, { recursive: true }); - fs.cpSync(standaloneRoot, outputDir, { recursive: true }); - - const relativeServer = path.relative(standaloneRoot, serverPath); - const deployedServerDir = path.dirname(path.join(outputDir, relativeServer)); - const deployedDistDir = path.join(deployedServerDir, distDir); - fs.mkdirSync(deployedDistDir, { recursive: true }); - fs.cpSync(path.join(buildDir, 'static'), path.join(deployedDistDir, 'static'), { - recursive: true, - }); - const publicDir = path.join(docsUiPath, 'public'); - if (fs.existsSync(publicDir)) { - fs.cpSync(publicDir, path.join(deployedServerDir, 'public'), { recursive: true }); - } - fs.writeFileSync( - path.join(outputDir, '.cortex-docs-build.json'), - `${JSON.stringify({ schemaVersion: 1, server: relativeServer }, null, 2)}\n`, - 'utf-8', - ); + fs.cpSync(exportDir, outputDir, { recursive: true }); } finally { fs.rmSync(runtimeDir, { recursive: true, force: true }); } - this.logger.success(`Docs built to ${outputDir}`); - this.logger.info(`Start the build with: cortex docs start --output ${outputDir}`); + this.logger.success(`Static docs built to ${outputDir}`); + this.logger.info('Deploy this directory to a static web host.'); } @Option({ flags: '-s, --spec ', description: 'Path to OpenAPI spec file' }) @@ -117,27 +112,4 @@ export class DocsBuildCommand extends CommandRunner { parseOutput(val: string): string { return val; } - - private findStandaloneServer(directory: string): string | undefined { - if (!fs.existsSync(directory)) return undefined; - for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { - const candidate = path.join(directory, entry.name); - if (entry.isFile() && entry.name === 'package.json') { - try { - const packageJson = JSON.parse(fs.readFileSync(candidate, 'utf-8')) as { name?: string }; - const serverPath = path.join(directory, 'server.js'); - if (packageJson.name === '@cortex-docs/docs-ui' && fs.existsSync(serverPath)) { - return serverPath; - } - } catch { - // Ignore unrelated package manifests that cannot be parsed. - } - } - if (entry.isDirectory()) { - const nested = this.findStandaloneServer(candidate); - if (nested) return nested; - } - } - return undefined; - } } diff --git a/packages/cli/src/commands/docs/docs.command.ts b/packages/cli/src/commands/docs/docs.command.ts index 005d82d..47e982f 100644 --- a/packages/cli/src/commands/docs/docs.command.ts +++ b/packages/cli/src/commands/docs/docs.command.ts @@ -1,12 +1,11 @@ import { Command, CommandRunner } from 'nest-commander'; import { DocsServeCommand } from './serve.command'; import { DocsBuildCommand } from './build.command'; -import { DocsStartCommand } from './start.command'; @Command({ name: 'docs', description: 'API documentation commands', - subCommands: [DocsServeCommand, DocsBuildCommand, DocsStartCommand], + subCommands: [DocsServeCommand, DocsBuildCommand], }) export class DocsCommand extends CommandRunner { async run(): Promise { diff --git a/packages/cli/src/commands/docs/start.command.ts b/packages/cli/src/commands/docs/start.command.ts deleted file mode 100644 index 4992d80..0000000 --- a/packages/cli/src/commands/docs/start.command.ts +++ /dev/null @@ -1,102 +0,0 @@ -import * as fs from 'node:fs'; -import * as path from 'node:path'; -import { spawn } from 'node:child_process'; -import { SubCommand, CommandRunner, Option } from 'nest-commander'; -import { - getAllLanguageTemplateDirs, - getFirstSpecPath, - resolveGeneratorTemplateRoot, -} from '@cortex-docs/core'; -import { LoggerService } from '../../services/logger.service'; -import { ProjectService } from '../../services/project.service'; - -@SubCommand({ - name: 'start', - description: 'Start a production Cortex Docs build', -}) -export class DocsStartCommand extends CommandRunner { - constructor( - private readonly logger: LoggerService, - private readonly project: ProjectService, - ) { - super(); - } - - async run(_params: string[], options: { output?: string; port?: number }): Promise { - const configPath = await this.project.findConfig(); - if (!configPath) throw new Error('No cortex.config.yml file was found.'); - const absoluteConfigPath = path.resolve(configPath); - const config = await this.project.loadConfig(absoluteConfigPath); - const outputDir = path.resolve(options.output ?? '.cortex/docs'); - const port = options.port ?? 3012; - const templateRoot = resolveGeneratorTemplateRoot(config, absoluteConfigPath); - const languageTemplateDirs = getAllLanguageTemplateDirs(config, absoluteConfigPath); - - const manifestPath = path.join(outputDir, '.cortex-docs-build.json'); - if (!fs.existsSync(manifestPath)) { - throw new Error( - `No production documentation build was found at ${outputDir}. Run \`cortex docs build\` first.`, - ); - } - - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { - schemaVersion?: number; - server?: string; - }; - if (manifest.schemaVersion !== 1 || !manifest.server) { - throw new Error(`The production documentation build at ${outputDir} is not valid.`); - } - const serverPath = path.resolve(outputDir, manifest.server); - if (!serverPath.startsWith(`${outputDir}${path.sep}`) || !fs.existsSync(serverPath)) { - throw new Error(`The production documentation server is missing from ${outputDir}.`); - } - const env: NodeJS.ProcessEnv = { - ...process.env, - CORTEX_CONFIG_PATH: absoluteConfigPath, - CORTEX_SPEC_PATH: getFirstSpecPath(config, 'openapi-spec'), - CORTEX_ASYNCAPI_PATH: getFirstSpecPath(config, 'asyncapi-spec'), - CORTEX_GRAPHQL_PATH: getFirstSpecPath(config, 'graphql-spec'), - CORTEX_GRPC_PATH: getFirstSpecPath(config, 'grpc-spec'), - CORTEX_OPENRPC_PATH: getFirstSpecPath(config, 'openrpc-spec'), - CORTEX_LOGO_PATH: config.logo, - CORTEX_FAVICON_PATH: config.favicon, - CORTEX_TEMPLATE_ROOT: templateRoot, - CORTEX_LANGUAGE_TEMPLATE_DIRS: - languageTemplateDirs.length > 0 ? JSON.stringify(languageTemplateDirs) : undefined, - PORT: String(port), - HOSTNAME: process.env.HOSTNAME ?? '0.0.0.0', - }; - - this.logger.info(`Starting Cortex Docs at http://localhost:${port}`); - const child = spawn(process.execPath, [serverPath], { - cwd: path.dirname(serverPath), - env, - stdio: 'inherit', - }); - - const exitCode = await new Promise((resolve, reject) => { - child.once('error', reject); - child.once('exit', (code, signal) => { - if (signal) reject(new Error(`The documentation server stopped with signal ${signal}.`)); - else resolve(code ?? 1); - }); - }); - if (exitCode !== 0) { - throw new Error(`The documentation server stopped with exit code ${exitCode}.`); - } - } - - @Option({ flags: '-o, --output ', description: 'Production build directory' }) - parseOutput(value: string): string { - return value; - } - - @Option({ flags: '-p, --port ', description: 'Port number' }) - parsePort(value: string): number { - const port = Number.parseInt(value, 10); - if (!Number.isInteger(port) || port < 1 || port > 65_535) { - throw new Error('The port must be an integer from 1 through 65535.'); - } - return port; - } -} diff --git a/packages/docs-site/docs/api-docs.md b/packages/docs-site/docs/api-docs.md index b7bb50f..d2808ad 100644 --- a/packages/docs-site/docs/api-docs.md +++ b/packages/docs-site/docs/api-docs.md @@ -31,15 +31,13 @@ The development server watches the configuration, specifications, Markdown files cortex docs build --output .cortex/docs ``` -This command creates a self-contained Node.js server. The result is not a static HTML export. +This command exports static HTML, CSS, JavaScript, and data files to `.cortex/docs`. Use `--output` to select another directory. -Start the result with this command: +Deploy the output directory to a static web host. Configure the host to resolve page URLs such as `/docs/quickstart` to `/docs/quickstart.html`. -```bash -NODE_ENV=production cortex docs start --output .cortex/docs --port 3000 -``` +The deployed site needs no Node.js server or access to the original configuration and specifications. The export includes documentation data and local assets. -Deploy the output directory to a service that can run Node.js. Keep the configuration file and all referenced local files available at their original paths. +Rebuild the site after source changes. Use `cortex docs serve` for a local preview with file watching. ## Configure site identity diff --git a/packages/docs-site/docs/quickstart.md b/packages/docs-site/docs/quickstart.md index a14755a..4b5011b 100644 --- a/packages/docs-site/docs/quickstart.md +++ b/packages/docs-site/docs/quickstart.md @@ -75,7 +75,7 @@ Cortex Docs adds these pages to the documentation site. The generated MCP server cortex generate ``` -This command generates SDKs, the MCP server, and documentation for all configured sources and languages. +This command generates SDKs and the MCP server for all configured sources and languages. ### Generate only the MCP server @@ -93,12 +93,23 @@ cortex docs serve This command starts a local documentation server. The server watches the configuration and source files, then regenerates the SDKs after changes. +### Build documentation for deployment + +```bash +cortex docs build --output .cortex/docs +``` + +The output contains static HTML, CSS, JavaScript, and documentation data. Deploy this directory to a static web host. The deployed site needs no Node.js server. + +Rebuild the site after source changes. See [Documentation](/docs/documentation) for hosting instructions. + ## How It Works 1. **Parse** — Cortex parses and validates each API specification from a file or URL 2. **Resolve** — Cortex resolves local component references when code generation needs their values 3. **Transform** — Cortex groups operations into resources with tags or `x-cortex-resource` -4. **Generate** — Cortex creates SDKs, documentation, and an MCP server from the project configuration +4. **Generate** — Cortex creates SDKs and an MCP server from the project configuration +5. **Document** — `cortex docs serve` previews the site, and `cortex docs build` exports static HTML for deployment ## Connection and Stream Behavior @@ -126,8 +137,7 @@ The exact option names follow the conventions of each generated language. The SD | `cortex publish --dry-run` | Preview publish commands | | `cortex validate` | Validate the configuration and each API specification | | `cortex docs serve` | Preview docs and regenerate SDKs after source changes | -| `cortex docs build` | Build a production Node.js documentation server | -| `cortex docs start` | Start a production documentation build | +| `cortex docs build` | Build static HTML documentation for deployment | | `cortex mcp generate` | Generate an MCP server standalone | ## Supported Languages diff --git a/packages/docs-ui/README.md b/packages/docs-ui/README.md index 07cbd97..80e555c 100644 --- a/packages/docs-ui/README.md +++ b/packages/docs-ui/README.md @@ -2,6 +2,10 @@ `@cortex-docs/docs-ui` is the documentation runtime for Cortex Docs projects. -The [`@cortex-docs/cli`](https://www.npmjs.com/package/@cortex-docs/cli) package installs and starts this package. Direct use is not supported. +The [`@cortex-docs/cli`](https://www.npmjs.com/package/@cortex-docs/cli) package installs this package. Use `cortex docs serve` for a local preview with file watching. + +Use `cortex docs build` to export static HTML, CSS, JavaScript, and documentation data. The deployed site needs no Node.js server. + +Direct use of this package is not supported. Read the [Cortex Docs repository](https://github.com/cortex-docs/cortex) for usage and contribution information. diff --git a/packages/docs-ui/app/api/docs-watch/route.ts b/packages/docs-ui/app/api/docs-watch/route.ts index cd2010b..29a99ca 100644 --- a/packages/docs-ui/app/api/docs-watch/route.ts +++ b/packages/docs-ui/app/api/docs-watch/route.ts @@ -16,11 +16,7 @@ const IGNORE = /[\\/](generated|node_modules|\.next)[\\/]/; export const dynamic = 'force-static'; export async function GET() { - if ( - process.env.NODE_ENV === 'production' || - process.env.CORTEX_STATIC_EXPORT === '1' || - process.env.CORTEX_STANDALONE_BUILD === '1' - ) { + if (process.env.NODE_ENV === 'production' || process.env.CORTEX_STATIC_EXPORT === '1') { return new Response(null, { status: 204 }); } diff --git a/packages/docs-ui/app/docs/[slug]/page.tsx b/packages/docs-ui/app/docs/[slug]/page.tsx index bf8818a..5fa619b 100644 --- a/packages/docs-ui/app/docs/[slug]/page.tsx +++ b/packages/docs-ui/app/docs/[slug]/page.tsx @@ -204,7 +204,7 @@ export default function DocSlugPage({ params }: { params: Promise<{ slug: string
-
+
{activeDoc ? ( <> diff --git a/packages/docs-ui/app/docs/docs-shell.tsx b/packages/docs-ui/app/docs/docs-shell.tsx index 53e3e79..b5757be 100644 --- a/packages/docs-ui/app/docs/docs-shell.tsx +++ b/packages/docs-ui/app/docs/docs-shell.tsx @@ -11,6 +11,10 @@ import { } from 'react'; import Link from 'next/link'; import { usePathname } from 'next/navigation'; +import { MenuIcon } from 'lucide-react'; + +import { Button } from '@/components/ui/button'; +import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '@/components/ui/sheet'; import { DocsHeader } from '@/components/docs/docs-header'; import { useProjectWatch } from '@/lib/use-project-watch'; @@ -46,6 +50,7 @@ export function useDocs(): DocsContextValue { export function DocsShell({ children }: { children: ReactNode }) { const pathname = usePathname(); + const [navigationOpen, setNavigationOpen] = useState(false); const [data, setData] = useState(null); const fetchDocs = useCallback(() => { @@ -67,40 +72,64 @@ export function DocsShell({ children }: { children: ReactNode }) { ? pathname.slice('/docs/'.length).split('/')[0] : undefined; + const navigation = ( + + ); + return (
+ + + + + + + Documentation + +
{navigation}
+ +
-
diff --git a/packages/docs-ui/components/docs/docs-header.tsx b/packages/docs-ui/components/docs/docs-header.tsx index 9fbd38d..474cbe4 100644 --- a/packages/docs-ui/components/docs/docs-header.tsx +++ b/packages/docs-ui/components/docs/docs-header.tsx @@ -311,36 +311,36 @@ export function DocsHeader() { return ( <>
-
+
{/* Left: logo */} -
- +
+ {hasCustomLogo && (logoDarkSvg || logoLightSvg) ? ( <> {logoDarkSvg && ( )} {logoLightSvg && ( )} {!logoLightSvg && logoDarkSvg && ( )} {!logoDarkSvg && logoLightSvg && ( @@ -348,7 +348,7 @@ export function DocsHeader() { ) : hasCustomLogo && logoSvg ? ( @@ -357,11 +357,11 @@ export function DocsHeader() { src="/api/logo" alt="Logo" style={{ height: logoHeight ?? 28 }} - className="w-auto" + className="min-w-0 w-auto object-contain" /> ) : ( )} {!hasCustomLogo && ( - + {project || siteTitle || 'Cortex'} )} {showLogoDocsLabel !== false && ( - Docs + Docs )}
{/* Center: search bar */} -
+
@@ -437,7 +438,7 @@ export function DocsHeader() {
{/* Bottom row: nav links */} -