diff --git a/.changeset/kind-files-press.md b/.changeset/kind-files-press.md new file mode 100644 index 0000000000..edc19b7a76 --- /dev/null +++ b/.changeset/kind-files-press.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs-backend': minor +'@backstage/plugin-techdocs-node': minor +--- + +Add support for disabling external font downloads via app-config option `techdocs.generator.mkdocs.disableExternalFonts`, useful for air-gapped Backstage instances. diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 33faf44841..27725e50fa 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -551,7 +551,31 @@ Done! You now have support for TechDocs in your own software template! ### Prevent download of Google 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 adding the following lines to mkdocs.yaml: +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. + +#### Using app-config + +Add the following configuration to your `app-config.yaml` to automatically +disable external font downloads for all TechDocs sites: + +```yaml +techdocs: + generator: + mkdocs: + 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.yaml` +file: ```yaml theme: @@ -561,7 +585,11 @@ theme: :::note Note -The addition `name: material` is necessary. Otherwise it will not work +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. ::: diff --git a/plugins/techdocs-backend/config.d.ts b/plugins/techdocs-backend/config.d.ts index 87369f2ccd..65e536bfd5 100644 --- a/plugins/techdocs-backend/config.d.ts +++ b/plugins/techdocs-backend/config.d.ts @@ -76,6 +76,14 @@ 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. + * If set to true, the external font will be disabled for all TechDocs sites. + * If set to false, the external font will be enabled for all TechDocs sites. + */ + disableExternalFonts?: boolean; }; }; diff --git a/plugins/techdocs-node/src/stages/generate/helpers.test.ts b/plugins/techdocs-node/src/stages/generate/helpers.test.ts index 1f198b43e9..8f6331b621 100644 --- a/plugins/techdocs-node/src/stages/generate/helpers.test.ts +++ b/plugins/techdocs-node/src/stages/generate/helpers.test.ts @@ -37,6 +37,7 @@ import { patchMkdocsYmlPreBuild, patchMkdocsYmlWithPlugins, sanitizeMkdocsYml, + patchMkdocsYmlWithFontDisabled } from './mkdocsPatchers'; import yaml from 'js-yaml'; @@ -468,6 +469,101 @@ describe('helpers', () => { }); }); + describe('patchMkdocsYmlWithFontDisabled', () => { + beforeEach(() => { + mockDir.setContent({ + 'mkdocs_without_theme.yml': `site_name: Test Site +docs_dir: docs +`, + 'mkdocs_with_theme_no_font.yml': `site_name: Test Site +docs_dir: docs +theme: + name: material +`, + 'mkdocs_with_theme_font_true.yml': `site_name: Test Site +docs_dir: docs +theme: + name: material + font: true +`, + 'mkdocs_with_theme_font_false.yml': `site_name: Test Site +docs_dir: docs +theme: + name: material + font: false +`, + }); + }); + + it('should create theme section with font disabled when no theme exists', async () => { + await patchMkdocsYmlWithFontDisabled( + mockDir.resolve('mkdocs_without_theme.yml'), + mockLogger, + ); + + const updatedMkdocsYml = await fs.readFile( + mockDir.resolve('mkdocs_without_theme.yml'), + ); + const parsedYml = yaml.load(updatedMkdocsYml.toString()) as { + theme?: { name?: string; font?: boolean }; + }; + expect(parsedYml.theme).toBeDefined(); + expect(parsedYml.theme?.name).toBe('material'); + expect(parsedYml.theme?.font).toBe(false); + }); + + it('should add font: false when theme exists but font is not configured', async () => { + await patchMkdocsYmlWithFontDisabled( + mockDir.resolve('mkdocs_with_theme_no_font.yml'), + mockLogger, + ); + + const updatedMkdocsYml = await fs.readFile( + mockDir.resolve('mkdocs_with_theme_no_font.yml'), + ); + const parsedYml = yaml.load(updatedMkdocsYml.toString()) as { + theme?: { name?: string; font?: boolean }; + }; + expect(parsedYml.theme).toBeDefined(); + expect(parsedYml.theme?.name).toBe('material'); + expect(parsedYml.theme?.font).toBe(false); + }); + + it('should not override font when font is already set to true', async () => { + await patchMkdocsYmlWithFontDisabled( + mockDir.resolve('mkdocs_with_theme_font_true.yml'), + mockLogger, + ); + + const updatedMkdocsYml = await fs.readFile( + mockDir.resolve('mkdocs_with_theme_font_true.yml'), + ); + const parsedYml = yaml.load(updatedMkdocsYml.toString()) as { + theme?: { name?: string; font?: boolean }; + }; + expect(parsedYml.theme).toBeDefined(); + expect(parsedYml.theme?.name).toBe('material'); + expect(parsedYml.theme?.font).toBe(true); + }); + + it('should not override font when font is already set to false', async () => { + await patchMkdocsYmlWithFontDisabled( + mockDir.resolve('mkdocs_with_theme_font_false.yml'), + mockLogger, + ); + + const updatedMkdocsYml = await fs.readFile( + mockDir.resolve('mkdocs_with_theme_font_false.yml'), + ); + const parsedYml = yaml.load(updatedMkdocsYml.toString()) as { + theme?: { name?: string; font?: boolean }; + }; + expect(parsedYml.theme).toBeDefined(); + expect(parsedYml.theme?.name).toBe('material'); + expect(parsedYml.theme?.font).toBe(false); + }); + }); + describe('patchIndexPreBuild', () => { afterEach(() => { warn.mockClear(); diff --git a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts b/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts index d676237b01..5f87a85c9d 100644 --- a/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts +++ b/plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts @@ -25,11 +25,17 @@ import { assertError } from '@backstage/errors'; import { ScmIntegrationRegistry } from '@backstage/integration'; import { LoggerService } from '@backstage/backend-plugin-api'; +const MATERIAL_THEME = 'material'; + type MkDocsObject = { plugins?: string[]; docs_dir: string; repo_url?: string; edit_uri?: string; + theme?: { + name?: string; + font?: boolean; + }; }; const patchMkdocsFile = async ( @@ -185,6 +191,39 @@ export const patchMkdocsYmlWithPlugins = async ( }); }; +/** + * Disable external font download for the material theme. + * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site + * @param logger + */ +export const patchMkdocsYmlWithFontDisabled = async ( + mkdocsYmlPath: string, + logger: LoggerService, +) => { + await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => { + if (!('theme' in mkdocsYml)) { + // No theme section exists, create it with font disabled + mkdocsYml.theme = { + name: MATERIAL_THEME, + font: false, + }; + return true; + } + + // Theme section exists, check if font is not configured, add font: false + if ( + mkdocsYml.theme && + typeof mkdocsYml.theme === 'object' && + !('font' in mkdocsYml.theme) + ) { + mkdocsYml.theme.font = false; + return true; + } + + return false; + }); +}; + /** * Sanitize mkdocs.yml by keeping only allowed configuration keys. * @@ -249,3 +288,4 @@ 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 8a764eb391..905d2e3cb9 100644 --- a/plugins/techdocs-node/src/stages/generate/techdocs.ts +++ b/plugins/techdocs-node/src/stages/generate/techdocs.ts @@ -32,6 +32,7 @@ import { import { patchMkdocsYmlPreBuild, + patchMkdocsYmlWithFontDisabled, patchMkdocsYmlWithPlugins, sanitizeMkdocsYml, } from './mkdocsPatchers'; @@ -150,6 +151,9 @@ export class TechdocsGenerator implements GeneratorBase { } await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins); + if (this.options.disableExternalFonts) { + await patchMkdocsYmlWithFontDisabled(mkdocsYmlPath, childLogger); + } // Directories to bind on container const mountDirs = { @@ -264,5 +268,8 @@ export function readGeneratorConfig( dangerouslyAllowAdditionalKeys: config.getOptionalStringArray( 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys', ), + disableExternalFonts: config.getOptionalBoolean( + 'techdocs.generator.mkdocs.disableExternalFonts' + ), }; } diff --git a/plugins/techdocs-node/src/stages/generate/types.ts b/plugins/techdocs-node/src/stages/generate/types.ts index b716e9510b..65243129ed 100644 --- a/plugins/techdocs-node/src/stages/generate/types.ts +++ b/plugins/techdocs-node/src/stages/generate/types.ts @@ -46,6 +46,7 @@ export type GeneratorConfig = { legacyCopyReadmeMdToIndexMd?: boolean; defaultPlugins?: string[]; dangerouslyAllowAdditionalKeys?: string[]; + disableExternalFonts?: boolean; }; /**