From 610b42f72f2391a70daf9b574c82ec7bdadca092 Mon Sep 17 00:00:00 2001 From: Karthik Date: Wed, 29 Apr 2026 00:15:28 +0530 Subject: [PATCH] update documentation and improve types Signed-off-by: Karthik --- .../config/vocabularies/Backstage/accept.txt | 4 +- docs/features/techdocs/configuration.md | 27 +++++++++++ docs/features/techdocs/how-to-guides.md | 33 ++++---------- .../src/stages/generate/helpers.test.ts | 18 ++++++++ .../src/stages/generate/mkdocsPatchers.ts | 45 +++++++++---------- 5 files changed, 77 insertions(+), 50 deletions(-) diff --git a/.github/vale/config/vocabularies/Backstage/accept.txt b/.github/vale/config/vocabularies/Backstage/accept.txt index c5a5deb5e0..17f8fe8173 100644 --- a/.github/vale/config/vocabularies/Backstage/accept.txt +++ b/.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 \ No newline at end of file +zsh \ No newline at end of file diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index cf9215ebc3..9c8c0dfc90 100644 --- a/docs/features/techdocs/configuration.md +++ b/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` diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index e8b1304115..9b4ec586d0 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/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 diff --git a/plugins/techdocs-node/src/stages/generate/helpers.test.ts b/plugins/techdocs-node/src/stages/generate/helpers.test.ts index 23eeaaa20e..ee4a07bf3c 100644 --- a/plugins/techdocs-node/src/stages/generate/helpers.test.ts +++ b/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', () => { diff --git a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts b/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts index 28c5928de6..4ba0040086 100644 --- a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts +++ b/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;