From 329f5920b68093f59bb8a45f7e64af678c5f5c2c Mon Sep 17 00:00:00 2001 From: Karthik Date: Tue, 25 Nov 2025 14:16:44 +0530 Subject: [PATCH] feat(techdocs): add techdocs-cli option to disable external font download Signed-off-by: Karthik --- .changeset/funny-animals-prove.md | 5 +++++ .../vale/config/vocabularies/Backstage/accept.txt | 1 + docs/features/techdocs/cli.md | 2 ++ docs/features/techdocs/how-to-guides.md | 14 +++++++++++++- packages/techdocs-cli/cli-report.md | 1 + .../techdocs-cli/src/commands/generate/generate.ts | 2 ++ packages/techdocs-cli/src/commands/index.ts | 5 +++++ plugins/techdocs-backend/config.d.ts | 2 +- .../src/stages/generate/helpers.test.ts | 2 +- .../src/stages/generate/mkdocsPatchers.ts | 14 ++++++++++++-- .../techdocs-node/src/stages/generate/techdocs.ts | 2 +- 11 files changed, 44 insertions(+), 6 deletions(-) create mode 100644 .changeset/funny-animals-prove.md diff --git a/.changeset/funny-animals-prove.md b/.changeset/funny-animals-prove.md new file mode 100644 index 0000000000..e4116a8d23 --- /dev/null +++ b/.changeset/funny-animals-prove.md @@ -0,0 +1,5 @@ +--- +'@techdocs/cli': minor +--- + +Add support for disabling external font downloads via techdocs-cli `techdocs-cli generate --disableExternalFonts`, useful for air-gapped Backstage instances. diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index 0a96735646..c5a5deb5e0 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.github/vale/config/vocabularies/Backstage/accept.txt @@ -587,3 +587,4 @@ zod Zolotusky zoomable zsh +patcher \ No newline at end of file diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index fa3d9148e2..616acb01e6 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -149,6 +149,8 @@ Options: Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file. --legacyCopyReadmeMdToIndexMd Attempt to ensure an index.md exists falling back to using /README.md or README.md in case a default /index.md is not provided. (default: false) + --disableExternalFonts Disable external font downloads for all TechDocs sites. Useful for air-gapped environments + where Google fonts cannot be accessed. (default: false) --runAsDefaultUser Bypass setting the container user as the same user and group id as host for Linux and MacOS (default: false) -v, --verbose Enable verbose output. (default: false) -h, --help display help for command diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 27725e50fa..e8b1304115 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -574,7 +574,7 @@ your file-level configuration and not override it. #### Manual configuration in mkdocs.yml -Alternatively, you can manually add the following configuration to your `mkdocs.yaml` +Alternatively, you can manually add the following configuration to your `mkdocs.yml` file: ```yaml @@ -593,6 +593,18 @@ only adds `font: false` when the `font` property is not already configured. ::: +#### Using techdocs-cli in CI/CD + +When generating TechDocs sites in CI/CD workflows using `techdocs-cli`, you can +use the `--disableExternalFonts` flag: + +```bash +techdocs-cli generate --disableExternalFonts +``` + +This will automatically patch the `mkdocs.yml` file during the generation +process, just like the `app-config.yaml` option does for local generation. + ## How to enable iframes in TechDocs TechDocs uses the [DOMPurify](https://github.com/cure53/DOMPurify) library to diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index 667c4fb6b6..f682072cd7 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -27,6 +27,7 @@ Usage: techdocs-cli generate|build [options] Options: --defaultPlugin [defaultPlugins...] + --disableExternalFonts --docker-image --etag --legacyCopyReadmeMdToIndexMd diff --git a/packages/techdocs-cli/src/commands/generate/generate.ts b/packages/techdocs-cli/src/commands/generate/generate.ts index 9a009aff00..b5b38b13d7 100644 --- a/packages/techdocs-cli/src/commands/generate/generate.ts +++ b/packages/techdocs-cli/src/commands/generate/generate.ts @@ -42,6 +42,7 @@ export default async function generate(opts: OptionValues) { const dockerImage = opts.dockerImage; const pullImage = opts.pull; const legacyCopyReadmeMdToIndexMd = opts.legacyCopyReadmeMdToIndexMd; + const disableExternalFonts = opts.disableExternalFonts; const defaultPlugins = opts.defaultPlugin; logger.info(`Using source dir ${sourceDir}`); @@ -64,6 +65,7 @@ export default async function generate(opts: OptionValues) { mkdocs: { legacyCopyReadmeMdToIndexMd, omitTechdocsCorePlugin, + disableExternalFonts, defaultPlugins, }, }, diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index e69cf4671a..c169815afc 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -70,6 +70,11 @@ export function registerCommands(program: Command) { 'Attempt to ensure an index.md exists falling back to using /README.md or README.md in case a default /index.md is not provided.', false, ) + .option( + '--disableExternalFonts', + 'Disable external font downloads by default by setting theme.font: false in mkdocs.yml when not already configured. Useful for air-gapped environments where Google fonts cannot be accessed.', + false, + ) .option( '--defaultPlugin [defaultPlugins...]', 'Plugins which should be added automatically to the mkdocs.yaml file', diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index 65e536bfd5..64c7fdc35f 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/plugins/techdocs-backend/config.d.ts @@ -76,7 +76,7 @@ export interface Config { * @see https://www.mkdocs.org/user-guide/configuration/#hooks */ dangerouslyAllowAdditionalKeys?: string[]; - + /** * Disable external fonts for all TechDocs sites. * If not set, the default value is false. diff --git a/plugins/techdocs-node/src/stages/generate/helpers.test.ts b/plugins/techdocs-node/src/stages/generate/helpers.test.ts index 8f6331b621..23eeaaa20e 100644 --- a/plugins/techdocs-node/src/stages/generate/helpers.test.ts +++ b/plugins/techdocs-node/src/stages/generate/helpers.test.ts @@ -37,7 +37,7 @@ import { patchMkdocsYmlPreBuild, patchMkdocsYmlWithPlugins, sanitizeMkdocsYml, - patchMkdocsYmlWithFontDisabled + patchMkdocsYmlWithFontDisabled, } from './mkdocsPatchers'; import yaml from 'js-yaml'; diff --git a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts b/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts index 5f87a85c9d..28c5928de6 100644 --- a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts +++ b/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts @@ -210,16 +210,27 @@ export const patchMkdocsYmlWithFontDisabled = async ( return true; } - // Theme section exists, check if font is not configured, add font: false + // Theme section exists. Only modify it when the configured theme is Material if ( mkdocsYml.theme && typeof mkdocsYml.theme === 'object' && + (mkdocsYml.theme as any).name === MATERIAL_THEME && !('font' in mkdocsYml.theme) ) { mkdocsYml.theme.font = false; return true; } + if ( + mkdocsYml.theme && + typeof mkdocsYml.theme === 'object' && + (mkdocsYml.theme as any).name !== MATERIAL_THEME + ) { + logger.debug( + 'mkdocs.yml theme is not "material"; skipping font disabling patch', + ); + } + return false; }); }; @@ -288,4 +299,3 @@ export const sanitizeMkdocsYml = async ( return true; }); }; - diff --git a/plugins/techdocs-node/src/stages/generate/techdocs.ts b/plugins/techdocs-node/src/stages/generate/techdocs.ts index 905d2e3cb9..e3492f2043 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/plugins/techdocs-node/src/stages/generate/techdocs.ts @@ -269,7 +269,7 @@ export function readGeneratorConfig( 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys', ), disableExternalFonts: config.getOptionalBoolean( - 'techdocs.generator.mkdocs.disableExternalFonts' + 'techdocs.generator.mkdocs.disableExternalFonts', ), }; }