update documentation and improve types

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

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

@@ -343,6 +343,7 @@ params
 parseable
 passthrough
 passwordless
+patcher
 Patrik
 pattison
 Peloton
@@ -586,5 +587,4 @@ Zhou
 zod
 Zolotusky
 zoomable
-zsh
-patcher
+zsh

docs/features/techdocs/configuration.md

@@ -97,6 +97,33 @@ techdocs:
       legacyCopyReadmeMdToIndexMd: false
 ```
 
+#### Disable external fonts
+
+`techdocs.generator.mkdocs.disableExternalFonts`
+
+(Optional) Use this when the generator cannot reach the internet (for example air-gapped or restricted networks). MkDocs Material otherwise tries to download the Roboto font from Google during generation.
+
+When `true`, TechDocs patches each `mkdocs.yml` during generation: if no `theme` section exists it adds `name: material` and `font: false`; if a `theme` exists but `font` is omitted, it sets `font: false`; if `font` is already set in the file, your value is left unchanged.
+
+**Example:**
+
+```yaml
+techdocs:
+  generator:
+    mkdocs:
+      disableExternalFonts: true
+```
+
+Alternatively, configure `mkdocs.yml` manually:
+
+```yaml
+theme:
+  name: material
+  font: false
+```
+
+**Note:** When using `theme.font` in `mkdocs.yml`, `theme.name: material` is required. If `font` is already set in the file, app-config patching does not override it; it only adds `font: false` when `font` was not configured.
+
 #### Default Plugins
 
 `techdocs.generator.mkdocs.defaultPlugins`

docs/features/techdocs/how-to-guides.md

@@ -549,14 +549,15 @@ on how you have configured your `template.yaml`.
 
 Done! You now have support for TechDocs in your own software template!
 
-### Prevent download of Google fonts
+### Disable external fonts
 
-If your Backstage instance does not have internet access, the generation will fail. TechDocs tries to download the Roboto font from Google. You can disable it by configuring your `app-config.yaml` or by manually updating your `mkdocs.yml` file.
+`techdocs.generator.mkdocs.disableExternalFonts`
 
-#### Using app-config
+(Optional) Use this when the generator cannot reach the internet (for example air-gapped or restricted networks). MkDocs Material otherwise tries to download the Roboto font from Google during generation.
 
-Add the following configuration to your `app-config.yaml` to automatically
-disable external font downloads for all TechDocs sites:
+When `true`, TechDocs patches each `mkdocs.yml` during generation: if no `theme` section exists it adds `name: material` and `font: false`; if a `theme` exists but `font` is omitted, it sets `font: false`; if `font` is already set in the file, your value is left unchanged.
+
+**Example:**
 
 ```yaml
 techdocs:
@@ -565,17 +566,7 @@ techdocs:
       disableExternalFonts: true
 ```
 
-This configuration will automatically patch the `mkdocs.yml` file during the
-generation process. If no `theme` section exists, it will create one with `name:
-material` and `font: false`. If a `theme` section exists but `font` is not
-configured, it will add `font: false` to the existing theme. If `font` is
-already explicitly configured in your `mkdocs.yml`, the patcher will respect
-your file-level configuration and not override it.
-
-#### Manual configuration in mkdocs.yml
-
-Alternatively, you can manually add the following configuration to your `mkdocs.yml`
-file:
+Alternatively, configure `mkdocs.yml` manually:
 
 ```yaml
 theme:
@@ -583,15 +574,7 @@ theme:
   font: false
 ```
 
-:::note Note
-
-The addition `name: material` is necessary. Otherwise it will not work.
-
-If you explicitly set `font: true` or `font: false` in your `mkdocs.yml`, the
-app-config patcher will respect that setting and not override it. The patcher
-only adds `font: false` when the `font` property is not already configured.
-
-:::
+**Note:** When using `theme.font` in `mkdocs.yml`, `theme.name: material` is required. If `font` is already set in the file, app-config patching does not override it; it only adds `font: false` when `font` was not configured.
 
 #### Using techdocs-cli in CI/CD
 

plugins/techdocs-node/src/stages/generate/helpers.test.ts

@@ -491,8 +491,14 @@ docs_dir: docs
 theme:
   name: material
   font: false
+`,
+        'mkdocs_with_theme_non_material.yml': `site_name: Test Site
+docs_dir: docs
+theme:
+  name: test-theme
 `,
       });
+      mockLogger.debug.mockClear();
     });
 
     it('should create theme section with font disabled when no theme exists', async () => {
@@ -562,6 +568,18 @@ theme:
       expect(parsedYml.theme?.name).toBe('material');
       expect(parsedYml.theme?.font).toBe(false);
     });
+
+    it('should not patch when theme name is not material', async () => {
+      const fixturePath = mockDir.resolve('mkdocs_with_theme_non_material.yml');
+      const before = await fs.readFile(fixturePath, 'utf8');
+
+      await patchMkdocsYmlWithFontDisabled(fixturePath, mockLogger);
+
+      await expect(fs.readFile(fixturePath, 'utf8')).resolves.toEqual(before);
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'mkdocs.yml theme is not "material"; skipping font disabling patch',
+      );
+    });
   });
 
   describe('patchIndexPreBuild', () => {

plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts

@@ -27,15 +27,21 @@ import { LoggerService } from '@backstage/backend-plugin-api';
 
 const MATERIAL_THEME = 'material';
 
+type MkDocsThemeObject = {
+  name?: string;
+  font?: boolean;
+};
+
+function isThemeObject(theme: unknown): theme is MkDocsThemeObject {
+  return typeof theme === 'object' && theme !== null && !Array.isArray(theme);
+}
+
 type MkDocsObject = {
   plugins?: string[];
   docs_dir: string;
   repo_url?: string;
   edit_uri?: string;
-  theme?: {
-    name?: string;
-    font?: boolean;
-  };
+  theme?: MkDocsThemeObject;
 };
 
 const patchMkdocsFile = async (
@@ -210,25 +216,18 @@ export const patchMkdocsYmlWithFontDisabled = async (
       return true;
     }
 
-    // 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',
-      );
+    const theme = mkdocsYml.theme;
+    if (isThemeObject(theme)) {
+      // Theme section exists. Only modify it when the configured theme is Material
+      if (theme.name === MATERIAL_THEME && !('font' in theme)) {
+        theme.font = false;
+        return true;
+      }
+      if (theme.name !== MATERIAL_THEME) {
+        logger.debug(
+          'mkdocs.yml theme is not "material"; skipping font disabling patch',
+        );
+      }
     }
 
     return false;