diff --git a/.changeset/dry-camels-scream.md b/.changeset/dry-camels-scream.md new file mode 100644 index 0000000000..ea35cece7a --- /dev/null +++ b/.changeset/dry-camels-scream.md @@ -0,0 +1,5 @@ +--- +'@techdocs/cli': minor +--- + +Add `--preview-app-bundle-path` and `--preview-app-port` options to the `serve` command enabling previewing with apps other than the provided one diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 06eb83dfca..682c6a8f8f 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -70,6 +70,11 @@ a Backstage app server on port 3000. The Backstage app has a custom TechDocs API implementation, which uses the MkDocs preview server as a proxy to fetch the generated documentation files and assets. +Backstage instances might differ from the provided preview app in appearance and +behavior. To preview documentation with a different app, use +`--preview-app-bundle-path` with a path to the bundle of the app to use instead. +Typically, a `dist` or `build` directory. + NOTE: When using a custom `techdocs` docker image, make sure the entry point is also `ENTRYPOINT ["mkdocs"]` or override with `--docker-entrypoint`. @@ -81,14 +86,17 @@ Usage: techdocs-cli serve [options] Serve a documentation project locally in a Backstage app-like environment Options: - -i, --docker-image The mkdocs docker container to use (default: "spotify/techdocs") - --docker-entrypoint Override the image entrypoint - --docker-option Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12" - (can be added multiple times). - --no-docker Do not use Docker, use MkDocs executable in current user environment. - --mkdocs-port Port for MkDocs server to use (default: "8000") - -v --verbose Enable verbose output. (default: false) - -h, --help display help for command + -i, --docker-image The mkdocs docker container to use (default: "spotify/techdocs") + --docker-entrypoint Override the image entrypoint + --docker-option Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12" + (can be added multiple times). + --no-docker Do not use Docker, use MkDocs executable in current user environment. + --mkdocs-port Port for MkDocs server to use (default: "8000") + --preview-app-bundle-path Preview documentation using a web app other than the included one. + --preview-app-port Port where the preview will be served. + Can only be used with "--preview-app-bundle-path". (default: "3000") + -v --verbose Enable verbose output. (default: false) + -h, --help display help for command ``` ### Generate TechDocs site from a documentation project diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index cf5b2caf0f..9230fe9f1c 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -100,6 +100,8 @@ Options: --no-docker --mkdocs-port -v --verbose + --preview-app-bundle-path + --preview-app-port -h, --help ``` diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 03772d09d7..d4303ad306 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -18,6 +18,7 @@ import { Command } from 'commander'; import { TechdocsGenerator } from '@backstage/plugin-techdocs-node'; const defaultDockerImage = TechdocsGenerator.defaultDockerImage; +const defaultPreviewAppPort = '3000'; export function registerCommands(program: Command) { program @@ -251,6 +252,25 @@ export function registerCommands(program: Command) { ) .option('--mkdocs-port ', 'Port for MkDocs server to use', '8000') .option('-v --verbose', 'Enable verbose output.', false) + .option( + '--preview-app-bundle-path ', + 'Preview documentation using another web app', + ) + .option( + '--preview-app-port ', + 'Port for the preview app to be served on', + defaultPreviewAppPort, + ) + .hook('preAction', command => { + if ( + command.opts().previewAppPort !== defaultPreviewAppPort && + !command.opts().previewAppBundlePath + ) { + command.error( + '--preview-app-port can only be used together with --preview-app-bundle-path', + ); + } + }) .action(lazy(() => import('./serve/serve').then(m => m.default))); } diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index fd1febfb6c..d46c70678a 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -42,6 +42,10 @@ function findPreviewBundlePath(): string { } } +function getPreviewAppPath(opts: OptionValues): string { + return opts.previewAppBundlePath ?? findPreviewBundlePath(); +} + export default async function serve(opts: OptionValues) { const logger = createLogger({ verbose: opts.verbose }); @@ -52,10 +56,6 @@ export default async function serve(opts: OptionValues) { ? true : false; - // TODO: Backstage app port should also be configurable as a CLI option. However, since we bundle - // a backstage app, we define app.baseUrl in the app-config.yaml. - // Hence, it is complicated to make this configurable. - const backstagePort = 3000; const backstageBackendPort = 7007; const mkdocsDockerAddr = `http://0.0.0.0:${opts.mkdocsPort}`; @@ -115,9 +115,10 @@ export default async function serve(opts: OptionValues) { ); } - const port = isDevMode ? backstageBackendPort : backstagePort; + const port = isDevMode ? backstageBackendPort : opts.previewAppPort; + const previewAppPath = getPreviewAppPath(opts); const httpServer = new HTTPServer( - findPreviewBundlePath(), + previewAppPath, port, opts.mkdocsPort, opts.verbose,