feat(techdocs): add techdocs-cli option to disable external font download

Signed-off-by: Karthik <karthik.jk11@gmail.com>

.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.

.github/vale/config/vocabularies/Backstage/accept.txt

@@ -587,3 +587,4 @@ zod
 Zolotusky
 zoomable
 zsh
+patcher

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 <docs-dir>/README.md or README.md
                                   in case a default <docs-dir>/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

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

packages/techdocs-cli/cli-report.md

@@ -27,6 +27,7 @@ Usage: techdocs-cli generate|build [options]
 
 Options:
   --defaultPlugin [defaultPlugins...]
+  --disableExternalFonts
   --docker-image <DOCKER_IMAGE>
   --etag <ETAG>
   --legacyCopyReadmeMdToIndexMd

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,
         },
       },

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 <docs-dir>/README.md or README.md in case a default <docs-dir>/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',

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.

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';
 

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;
   });
 };
-

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',
     ),
   };
 }