@backstage/plugin-techdocs-node 2.2.1-next.2 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -0
- package/dist/alpha.d.ts +2 -1
- package/dist/stages/generate/mkdocsPatchers.cjs.js +62 -3
- package/dist/stages/generate/mkdocsPatchers.cjs.js.map +1 -1
- package/dist/stages/generate/techdocs.cjs.js +5 -1
- package/dist/stages/generate/techdocs.cjs.js.map +1 -1
- package/package.json +11 -11
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# @backstage/plugin-techdocs-node
|
|
2
2
|
|
|
3
|
+
## 2.3.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- a4604d2: Added a new `@backstage/plugin-techdocs-node/alpha` entry point with building blocks for implementing additional documentation engines in separate modules: `createDockerContainerRunner`, `createOrUpdateMetadata`, `storeEtagMetadata`, `runCommand`, `validateInputDirectory`, `patchIndexPreBuild`, and the `mkdocs.yml` helpers `MKDOCS_SCHEMA`, `validateMkdocsYaml` and `sanitizeMkdocsYml`. These are alpha and may change in minor releases.
|
|
8
|
+
|
|
9
|
+
### Patch Changes
|
|
10
|
+
|
|
11
|
+
- 686d3cb: Fixed TechDocs served from Azure Blob Storage or Google Cloud Storage keeping storage connections open when a browser navigates away before a file is fully loaded. Errors that occur while streaming a file from Azure Blob Storage are now also logged and handled, instead of being left unhandled.
|
|
12
|
+
- bc73976: Restricts `markdown_extensions` in `mkdocs.yml` to known extension names before documentation generation, in both the MkDocs and Zensical engines. Extension names outside the permitted set are removed from the configuration with a warning. Allow additional extensions, for example from a custom build image, with the new `techdocs.generator.mkdocs.dangerouslyAllowAdditionalExtensions` configuration, or the `--dangerouslyAllowAdditionalExtensions` flag when using the TechDocs CLI.
|
|
13
|
+
- 2e98895: Fixed TechDocs served from AWS S3 leaking S3 connections when a browser navigates away before a file is fully loaded. Over time the connection pool was exhausted and all TechDocs pages failed to load with `Socket timed out without establishing a connection` errors until the backend was restarted.
|
|
14
|
+
- Updated dependencies
|
|
15
|
+
- @backstage/integration-aws-node@0.2.4
|
|
16
|
+
- @backstage/integration@2.2.0
|
|
17
|
+
- @backstage/backend-plugin-api@1.12.0
|
|
18
|
+
- @backstage/errors@1.4.0
|
|
19
|
+
- @backstage/catalog-model@1.10.3
|
|
20
|
+
- @backstage/config@1.3.11
|
|
21
|
+
- @backstage/plugin-search-common@1.2.27
|
|
22
|
+
- @backstage/plugin-techdocs-common@0.1.3
|
|
23
|
+
|
|
24
|
+
## 2.2.2-next.2
|
|
25
|
+
|
|
26
|
+
### Patch Changes
|
|
27
|
+
|
|
28
|
+
- Bumped version to account for a patch release.
|
|
29
|
+
|
|
3
30
|
## 2.2.1-next.2
|
|
4
31
|
|
|
5
32
|
### Patch Changes
|
package/dist/alpha.d.ts
CHANGED
|
@@ -20,9 +20,10 @@ import 'node:stream';
|
|
|
20
20
|
* @param logger - A logger instance
|
|
21
21
|
* @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist
|
|
22
22
|
* @param additionalAllowedPlugins - Optional array of additional plugins to allow beyond the default set
|
|
23
|
+
* @param additionalAllowedExtensions - Optional array of additional markdown extensions to allow beyond the default set
|
|
23
24
|
* @alpha
|
|
24
25
|
*/
|
|
25
|
-
declare const sanitizeMkdocsYml: (mkdocsYmlPath: string, logger: LoggerService, additionalAllowedKeys?: string[], additionalAllowedPlugins?: string[]) => Promise<void>;
|
|
26
|
+
declare const sanitizeMkdocsYml: (mkdocsYmlPath: string, logger: LoggerService, additionalAllowedKeys?: string[], additionalAllowedPlugins?: string[], additionalAllowedExtensions?: string[]) => Promise<void>;
|
|
26
27
|
|
|
27
28
|
/**
|
|
28
29
|
* Creates a container runner that uses the local Docker daemon, the same one
|
|
@@ -33,6 +33,8 @@ var path__default = /*#__PURE__*/_interopDefaultCompat(path);
|
|
|
33
33
|
|
|
34
34
|
const MATERIAL_THEME = "material";
|
|
35
35
|
const PYMDOWNX_SNIPPETS_EXTENSION = "pymdownx.snippets";
|
|
36
|
+
const PYMDOWNX_EXTENSION_PREFIX = "pymdownx.";
|
|
37
|
+
const MARKDOWN_EXTENSIONS_PREFIX = "markdown.extensions.";
|
|
36
38
|
const DEFAULT_ALLOWED_MKDOCS_PLUGINS = /* @__PURE__ */ new Set([
|
|
37
39
|
"techdocs-core",
|
|
38
40
|
"search",
|
|
@@ -42,9 +44,47 @@ const DEFAULT_ALLOWED_MKDOCS_PLUGINS = /* @__PURE__ */ new Set([
|
|
|
42
44
|
"material/group"
|
|
43
45
|
]);
|
|
44
46
|
const MKDOCS_PLUGIN_GROUPS = /* @__PURE__ */ new Set(["group", "material/group"]);
|
|
47
|
+
const DEFAULT_ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([
|
|
48
|
+
// Built-in Python-Markdown extensions, bundled with the `markdown` package
|
|
49
|
+
// that both official TechDocs build images ship.
|
|
50
|
+
"abbr",
|
|
51
|
+
"admonition",
|
|
52
|
+
"attr_list",
|
|
53
|
+
"codehilite",
|
|
54
|
+
"def_list",
|
|
55
|
+
"extra",
|
|
56
|
+
"fenced_code",
|
|
57
|
+
"footnotes",
|
|
58
|
+
"legacy_attrs",
|
|
59
|
+
"legacy_em",
|
|
60
|
+
"md_in_html",
|
|
61
|
+
"meta",
|
|
62
|
+
"nl2br",
|
|
63
|
+
"sane_lists",
|
|
64
|
+
"smarty",
|
|
65
|
+
"tables",
|
|
66
|
+
"toc",
|
|
67
|
+
"wikilinks",
|
|
68
|
+
// Rendering extensions shipped in the official TechDocs build images.
|
|
69
|
+
"markdown_inline_graphviz",
|
|
70
|
+
"mdx_truly_sane_lists",
|
|
71
|
+
"plantuml_markdown",
|
|
72
|
+
"plantuml-markdown",
|
|
73
|
+
// Zensical's rendering extensions. Extensions that load code or files
|
|
74
|
+
// during generation are deliberately not allowed by default.
|
|
75
|
+
"zensical.extensions.autorefs",
|
|
76
|
+
"zensical.extensions.context",
|
|
77
|
+
"zensical.extensions.emoji",
|
|
78
|
+
"zensical.extensions.glightbox",
|
|
79
|
+
"zensical.extensions.links"
|
|
80
|
+
]);
|
|
45
81
|
function isPymdownxSnippetsExtension(extensionName) {
|
|
46
82
|
return extensionName === PYMDOWNX_SNIPPETS_EXTENSION || extensionName === `${PYMDOWNX_SNIPPETS_EXTENSION}:SnippetExtension`;
|
|
47
83
|
}
|
|
84
|
+
function isAllowedExtensionName(extensionName, allowedExtensions) {
|
|
85
|
+
const shortName = extensionName.startsWith(MARKDOWN_EXTENSIONS_PREFIX) ? extensionName.slice(MARKDOWN_EXTENSIONS_PREFIX.length) : extensionName;
|
|
86
|
+
return allowedExtensions.has(shortName) || shortName.startsWith(PYMDOWNX_EXTENSION_PREFIX);
|
|
87
|
+
}
|
|
48
88
|
function isPlainObject(value) {
|
|
49
89
|
if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof helpers.UnknownTag) {
|
|
50
90
|
return false;
|
|
@@ -250,7 +290,7 @@ const patchMkdocsYmlWithFontDisabled = async (mkdocsYmlPath, logger) => {
|
|
|
250
290
|
return false;
|
|
251
291
|
});
|
|
252
292
|
};
|
|
253
|
-
const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, additionalAllowedPlugins) => {
|
|
293
|
+
const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, additionalAllowedPlugins, additionalAllowedExtensions) => {
|
|
254
294
|
await patchMkdocsFileOrThrow(mkdocsYmlPath, logger, (mkdocsYml) => {
|
|
255
295
|
const allowedKeys = new Set(helpers.ALLOWED_MKDOCS_KEYS);
|
|
256
296
|
if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {
|
|
@@ -261,6 +301,17 @@ const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, a
|
|
|
261
301
|
);
|
|
262
302
|
additionalAllowedKeys.forEach((key) => allowedKeys.add(key));
|
|
263
303
|
}
|
|
304
|
+
const allowedExtensions = new Set(DEFAULT_ALLOWED_EXTENSIONS);
|
|
305
|
+
if (additionalAllowedExtensions && additionalAllowedExtensions.length > 0) {
|
|
306
|
+
logger.warn(
|
|
307
|
+
`DANGEROUS: Allowing additional MkDocs markdown extensions beyond the default safe allowlist: ${additionalAllowedExtensions.join(
|
|
308
|
+
", "
|
|
309
|
+
)}. Some markdown extensions execute code or load files from the documentation input directory. Only use in trusted environments.`
|
|
310
|
+
);
|
|
311
|
+
additionalAllowedExtensions.forEach(
|
|
312
|
+
(extension) => allowedExtensions.add(extension)
|
|
313
|
+
);
|
|
314
|
+
}
|
|
264
315
|
const removedKeys = Object.keys(mkdocsYml).filter(
|
|
265
316
|
(key) => !allowedKeys.has(key)
|
|
266
317
|
);
|
|
@@ -309,6 +360,10 @@ const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, a
|
|
|
309
360
|
removedEntries.push(ext);
|
|
310
361
|
return [];
|
|
311
362
|
}
|
|
363
|
+
if (!isAllowedExtensionName(ext, allowedExtensions)) {
|
|
364
|
+
removedEntries.push(ext);
|
|
365
|
+
return [];
|
|
366
|
+
}
|
|
312
367
|
return [ext];
|
|
313
368
|
}
|
|
314
369
|
if (!isPlainObject(ext)) {
|
|
@@ -325,6 +380,10 @@ const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, a
|
|
|
325
380
|
}
|
|
326
381
|
const sanitizedExtension = {};
|
|
327
382
|
for (const [extensionName, extensionConfig] of extensionEntries) {
|
|
383
|
+
if (!isAllowedExtensionName(extensionName, allowedExtensions)) {
|
|
384
|
+
removedEntries.push(extensionName);
|
|
385
|
+
continue;
|
|
386
|
+
}
|
|
328
387
|
if (extensionConfig instanceof helpers.UnknownTag) {
|
|
329
388
|
removedEntries.push(
|
|
330
389
|
`dynamically configured ${extensionName} extension`
|
|
@@ -370,9 +429,9 @@ const sanitizeMkdocsYml = async (mkdocsYmlPath, logger, additionalAllowedKeys, a
|
|
|
370
429
|
}
|
|
371
430
|
if (removedEntries.length > 0) {
|
|
372
431
|
logger.warn(
|
|
373
|
-
`Removed the following dangerous entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(
|
|
432
|
+
`Removed the following dangerous or unsupported entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(
|
|
374
433
|
", "
|
|
375
|
-
)}.`
|
|
434
|
+
)}. To allow additional markdown extensions, configure 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalExtensions' in your Backstage app-config. When using the TechDocs CLI, use '--dangerouslyAllowAdditionalExtensions' instead.`
|
|
376
435
|
);
|
|
377
436
|
}
|
|
378
437
|
if (removedCustomIcons) {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mkdocsPatchers.cjs.js","sources":["../../../src/stages/generate/mkdocsPatchers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fs from 'fs-extra';\nimport * as yaml from 'js-yaml';\nimport path from 'node:path';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport {\n ALLOWED_MKDOCS_KEYS,\n ALLOWED_THEME_KEYS,\n DANGEROUS_EXTENSION_CONFIG_KEYS,\n getRepoUrlFromLocationAnnotation,\n MKDOCS_SCHEMA,\n UnknownTag,\n} from './helpers';\nimport { toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport {\n LoggerService,\n resolveSafeChildPath,\n} from '@backstage/backend-plugin-api';\n\nconst MATERIAL_THEME = 'material';\nconst PYMDOWNX_SNIPPETS_EXTENSION = 'pymdownx.snippets';\n\nconst DEFAULT_ALLOWED_MKDOCS_PLUGINS = new Set([\n 'techdocs-core',\n 'search',\n 'material/search',\n 'redirects',\n 'group',\n 'material/group',\n]);\nconst MKDOCS_PLUGIN_GROUPS = new Set(['group', 'material/group']);\n\nfunction isPymdownxSnippetsExtension(extensionName: string): boolean {\n return (\n extensionName === PYMDOWNX_SNIPPETS_EXTENSION ||\n extensionName === `${PYMDOWNX_SNIPPETS_EXTENSION}:SnippetExtension`\n );\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n if (\n typeof value !== 'object' ||\n value === null ||\n Array.isArray(value) ||\n value instanceof UnknownTag\n ) {\n return false;\n }\n\n const prototype = Object.getPrototypeOf(value);\n return prototype === Object.prototype || prototype === null;\n}\n\nfunction normalizeMkdocsPlugins(plugins: unknown): unknown[] | undefined {\n if (Array.isArray(plugins)) {\n return plugins;\n }\n if (isPlainObject(plugins)) {\n return Object.entries(plugins).map(([name, config]) => ({\n [name]: config,\n }));\n }\n return undefined;\n}\n\nfunction sanitizeMkdocsPlugins(\n plugins: unknown,\n allowedPlugins: Set<string>,\n removedPlugins: Set<string>,\n): unknown[] {\n if (plugins instanceof UnknownTag) {\n removedPlugins.add('dynamically configured plugin name');\n return [];\n }\n\n const normalizedPlugins = normalizeMkdocsPlugins(plugins);\n if (!normalizedPlugins) {\n removedPlugins.add('malformed plugin declaration');\n return [];\n }\n\n const sanitizedPlugins: unknown[] = [];\n for (const plugin of normalizedPlugins) {\n if (plugin instanceof UnknownTag) {\n removedPlugins.add('dynamically configured plugin name');\n continue;\n }\n\n let pluginName: string;\n if (typeof plugin === 'string' && plugin.length > 0) {\n pluginName = plugin;\n } else if (isPlainObject(plugin) && Object.keys(plugin).length === 1) {\n [pluginName] = Object.keys(plugin);\n const config = plugin[pluginName];\n if (config !== null && !isPlainObject(config)) {\n removedPlugins.add('malformed plugin declaration');\n continue;\n }\n } else {\n removedPlugins.add('malformed plugin declaration');\n continue;\n }\n\n if (!allowedPlugins.has(pluginName)) {\n removedPlugins.add(pluginName);\n continue;\n }\n\n let sanitizedPlugin = plugin;\n if (isPlainObject(plugin)) {\n const config = plugin[pluginName];\n if (MKDOCS_PLUGIN_GROUPS.has(pluginName) && isPlainObject(config)) {\n sanitizedPlugin = {\n ...plugin,\n [pluginName]: {\n ...config,\n plugins: sanitizeMkdocsPlugins(\n config.plugins,\n allowedPlugins,\n removedPlugins,\n ),\n },\n };\n }\n }\n\n sanitizedPlugins.push(sanitizedPlugin);\n }\n\n return sanitizedPlugins;\n}\n\n// mkdocs-material globs SVGs from every `options.custom_icons` path with no\n// confinement, so the option must be an array of string paths that each\n// resolve inside the documentation input directory, which mkdocs runs from.\nfunction isConfinedCustomIcons(\n customIcons: unknown,\n inputDir: string,\n): boolean {\n if (!Array.isArray(customIcons)) {\n return false;\n }\n\n return customIcons.every(entry => {\n if (typeof entry !== 'string') {\n return false;\n }\n try {\n resolveSafeChildPath(inputDir, entry);\n return true;\n } catch {\n return false;\n }\n });\n}\n\ntype MkDocsThemeObject = {\n name?: string;\n font?: boolean;\n};\n\nfunction isThemeObject(theme: unknown): theme is MkDocsThemeObject {\n return typeof theme === 'object' && theme !== null && !Array.isArray(theme);\n}\n\ntype MkDocsObject = {\n plugins?: string[];\n docs_dir: string;\n repo_url?: string;\n edit_uri?: string;\n theme?: MkDocsThemeObject;\n};\n\nconst patchMkdocsFile = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n updateAction: (mkdocsYml: MkDocsObject) => boolean,\n options?: { failOnError?: boolean },\n) => {\n // We only want to override the mkdocs.yml if it has actually changed. This is relevant if\n // used with a 'dir' location on the file system as this would permanently update the file.\n let didEdit = false;\n\n let mkdocsYmlFileString;\n try {\n mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n } catch (error) {\n logger.warn(\n `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n\n let mkdocsYml: any;\n try {\n mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });\n\n // mkdocsYml should be an object type after successful parsing.\n // But based on its type definition, it can also be a string or undefined, which we don't want.\n if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {\n throw new Error('Bad YAML format.');\n }\n } catch (error) {\n logger.warn(\n `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n\n didEdit = updateAction(mkdocsYml);\n\n try {\n if (didEdit) {\n await fs.writeFile(\n mkdocsYmlPath,\n yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),\n 'utf8',\n );\n }\n } catch (error) {\n logger.warn(\n `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n};\n\nconst patchMkdocsFileOrThrow = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n updateAction: (mkdocsYml: MkDocsObject) => boolean,\n) =>\n patchMkdocsFile(mkdocsYmlPath, logger, updateAction, {\n failOnError: true,\n });\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add repo_url or edit_uri if it does not exists\n * If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.\n * If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get\n * the repository URL.\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n */\nexport const patchMkdocsYmlPreBuild = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n parsedLocationAnnotation: ParsedLocationAnnotation,\n scmIntegrations: ScmIntegrationRegistry,\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n if (!('repo_url' in mkdocsYml) || !('edit_uri' in mkdocsYml)) {\n // Add edit_uri and/or repo_url to mkdocs.yml if it is missing.\n // This will enable the Page edit button generated by MkDocs.\n // If the either has been set, keep the original value\n const result = getRepoUrlFromLocationAnnotation(\n parsedLocationAnnotation,\n scmIntegrations,\n mkdocsYml.docs_dir,\n );\n\n if (result.repo_url || result.edit_uri) {\n mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;\n mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;\n\n logger.info(\n `Set ${JSON.stringify(\n result,\n )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,\n );\n return true;\n }\n }\n return false;\n });\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add all provided default plugins\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param defaultPlugins - List of default mkdocs plugins\n */\nexport const patchMkdocsYmlWithPlugins = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n defaultPlugins: string[] = ['techdocs-core'],\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n // Modify mkdocs.yaml to contain the required default plugins.\n // If no plugins are defined we can just return the defaults.\n if (!('plugins' in mkdocsYml)) {\n mkdocsYml.plugins = defaultPlugins;\n return true;\n }\n\n // Otherwise, check each default plugin and include it if necessary.\n let changesMade = false;\n\n defaultPlugins.forEach(dp => {\n // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)\n // then we need to add it\n if (\n !(\n mkdocsYml.plugins!.includes(dp) ||\n mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))\n )\n ) {\n mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];\n changesMade = true;\n }\n });\n\n return changesMade;\n });\n};\n\n/**\n * Disable external font download for the material theme.\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger\n */\nexport const patchMkdocsYmlWithFontDisabled = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n if (!('theme' in mkdocsYml)) {\n // No theme section exists, create it with font disabled\n mkdocsYml.theme = {\n name: MATERIAL_THEME,\n font: false,\n };\n return true;\n }\n\n const theme = mkdocsYml.theme;\n if (isThemeObject(theme)) {\n // Theme section exists. Only modify it when the configured theme is Material\n if (theme.name === MATERIAL_THEME && !('font' in theme)) {\n theme.font = false;\n return true;\n }\n if (theme.name !== MATERIAL_THEME) {\n logger.debug(\n 'mkdocs.yml theme is not \"material\"; skipping font disabling patch',\n );\n }\n }\n\n return false;\n });\n};\n\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n * @param additionalAllowedPlugins - Optional array of additional plugins to allow beyond the default set\n * @alpha\n */\nexport const sanitizeMkdocsYml = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n additionalAllowedKeys?: string[],\n additionalAllowedPlugins?: string[],\n) => {\n await patchMkdocsFileOrThrow(mkdocsYmlPath, logger, mkdocsYml => {\n // Combine default allowed keys with additional keys\n const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n logger.warn(\n `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n ', ',\n )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n );\n additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n }\n\n // Identify keys that will be removed for logging\n const removedKeys = Object.keys(mkdocsYml).filter(\n key => !allowedKeys.has(key),\n );\n\n if (removedKeys.length > 0) {\n logger.warn(\n `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n ', ',\n )}. ` +\n `TechDocs only supports a subset of MkDocs configuration options.`,\n );\n }\n\n // Build a new object with only allowed keys\n const sanitized: Record<string, unknown> = {};\n for (const key of allowedKeys) {\n if (key in mkdocsYml) {\n sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n }\n }\n\n // Sanitize markdown_extensions\n const extensions = sanitized.markdown_extensions;\n const removedEntries: string[] = [];\n const inputDir = path.dirname(mkdocsYmlPath);\n let removedCustomIcons = false;\n const extensionMapping = isPlainObject(extensions) ? extensions : undefined;\n let normalizedExtensions: unknown[] | undefined;\n if (Array.isArray(extensions)) {\n normalizedExtensions = extensions;\n } else if (extensionMapping) {\n normalizedExtensions = Object.entries(extensionMapping).map(\n ([name, config]) => ({\n [name]: config,\n }),\n );\n }\n if (extensions instanceof UnknownTag) {\n removedEntries.push('dynamically configured extension');\n sanitized.markdown_extensions = [];\n } else if (normalizedExtensions) {\n const sanitizedExtensions = normalizedExtensions.flatMap<unknown>(ext => {\n if (ext instanceof UnknownTag) {\n removedEntries.push('dynamically configured extension');\n return [];\n }\n\n if (typeof ext === 'string') {\n if (isPymdownxSnippetsExtension(ext)) {\n return [ext];\n }\n\n if (ext.includes(':')) {\n removedEntries.push(ext);\n return [];\n }\n return [ext];\n }\n\n if (!isPlainObject(ext)) {\n removedEntries.push('malformed extension declaration');\n return [];\n }\n\n // Check every key, not just the first, so that a multi-key mapping\n // cannot smuggle a dangerous name past the filter.\n const extensionEntries = Object.entries(ext);\n const dangerousNames = extensionEntries\n .map(([extensionName]) => extensionName)\n .filter(\n extensionName =>\n extensionName.includes(':') &&\n !isPymdownxSnippetsExtension(extensionName),\n );\n if (dangerousNames.length > 0) {\n removedEntries.push(...dangerousNames);\n return [];\n }\n\n const sanitizedExtension: Record<string, unknown> = {};\n for (const [extensionName, extensionConfig] of extensionEntries) {\n if (extensionConfig instanceof UnknownTag) {\n removedEntries.push(\n `dynamically configured ${extensionName} extension`,\n );\n continue;\n }\n\n if (isPymdownxSnippetsExtension(extensionName)) {\n if (\n extensionConfig !== null &&\n (typeof extensionConfig !== 'object' ||\n Object.keys(extensionConfig).length > 0)\n ) {\n removedEntries.push(`${extensionName} configuration`);\n }\n sanitizedExtension[extensionName] = {};\n } else if (isPlainObject(extensionConfig)) {\n const sanitizedConfig = { ...extensionConfig };\n for (const dangerousKey of DANGEROUS_EXTENSION_CONFIG_KEYS) {\n if (dangerousKey in sanitizedConfig) {\n delete sanitizedConfig[dangerousKey];\n removedEntries.push(dangerousKey);\n }\n }\n\n const options = sanitizedConfig.options;\n // A tagged value such as `!ENV` resolves to a mapping at build\n // time, so its custom_icons cannot be checked here.\n if (options instanceof UnknownTag) {\n delete sanitizedConfig.options;\n removedCustomIcons = true;\n } else if (isPlainObject(options) && 'custom_icons' in options) {\n if (!isConfinedCustomIcons(options.custom_icons, inputDir)) {\n const sanitizedOptions = { ...options };\n delete sanitizedOptions.custom_icons;\n sanitizedConfig.options = sanitizedOptions;\n removedCustomIcons = true;\n }\n }\n sanitizedExtension[extensionName] = sanitizedConfig;\n } else {\n sanitizedExtension[extensionName] = extensionConfig;\n }\n }\n\n return Object.keys(sanitizedExtension).length > 0\n ? [sanitizedExtension]\n : [];\n });\n\n sanitized.markdown_extensions = extensionMapping\n ? Object.assign({}, ...sanitizedExtensions)\n : sanitizedExtensions;\n } else if (extensions !== undefined) {\n removedEntries.push('malformed extension declaration');\n sanitized.markdown_extensions = [];\n }\n\n if (removedEntries.length > 0) {\n logger.warn(\n `Removed the following dangerous entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(\n ', ',\n )}.`,\n );\n }\n\n if (removedCustomIcons) {\n logger.warn(\n `Removed the custom_icons option from markdown_extensions in mkdocs.yml because it must be an array of string paths inside the documentation input directory.`,\n );\n }\n\n if ('plugins' in sanitized) {\n const allowedPlugins = new Set(DEFAULT_ALLOWED_MKDOCS_PLUGINS);\n additionalAllowedPlugins?.forEach(plugin => allowedPlugins.add(plugin));\n\n const removedPlugins = new Set<string>();\n sanitized.plugins = sanitizeMkdocsPlugins(\n sanitized.plugins,\n allowedPlugins,\n removedPlugins,\n );\n\n if (removedPlugins.size > 0) {\n logger.warn(\n `Removed unsupported MkDocs plugins from mkdocs.yml: ${Array.from(\n removedPlugins,\n ).join(\n ', ',\n )}. To allow additional plugins, configure 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins' in your Backstage app-config. When using the TechDocs CLI, use '--defaultPlugin' instead.`,\n );\n }\n }\n\n // Clear the original object and copy sanitized values back\n for (const key of Object.keys(mkdocsYml)) {\n delete (mkdocsYml as Record<string, unknown>)[key];\n }\n Object.assign(mkdocsYml, sanitized);\n\n // Sanitize theme sub-keys\n const theme = (mkdocsYml as Record<string, unknown>).theme;\n if (isThemeObject(theme)) {\n const removedThemeKeys = Object.keys(theme).filter(\n key => !ALLOWED_THEME_KEYS.has(key),\n );\n if (removedThemeKeys.length > 0) {\n for (const key of removedThemeKeys) {\n delete (theme as Record<string, unknown>)[key];\n }\n logger.warn(\n `Removed the following unsupported keys from theme configuration in mkdocs.yml: ${removedThemeKeys.join(\n ', ',\n )}.`,\n );\n }\n }\n\n // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n return true;\n });\n};\n"],"names":["UnknownTag","resolveSafeChildPath","fs","toError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS","path","DANGEROUS_EXTENSION_CONFIG_KEYS","ALLOWED_THEME_KEYS"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"mkdocsPatchers.cjs.js","sources":["../../../src/stages/generate/mkdocsPatchers.ts"],"sourcesContent":["/*\n * Copyright 2022 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport fs from 'fs-extra';\nimport * as yaml from 'js-yaml';\nimport path from 'node:path';\nimport { ParsedLocationAnnotation } from '../../helpers';\nimport {\n ALLOWED_MKDOCS_KEYS,\n ALLOWED_THEME_KEYS,\n DANGEROUS_EXTENSION_CONFIG_KEYS,\n getRepoUrlFromLocationAnnotation,\n MKDOCS_SCHEMA,\n UnknownTag,\n} from './helpers';\nimport { toError } from '@backstage/errors';\nimport { ScmIntegrationRegistry } from '@backstage/integration';\nimport {\n LoggerService,\n resolveSafeChildPath,\n} from '@backstage/backend-plugin-api';\n\nconst MATERIAL_THEME = 'material';\nconst PYMDOWNX_SNIPPETS_EXTENSION = 'pymdownx.snippets';\nconst PYMDOWNX_EXTENSION_PREFIX = 'pymdownx.';\nconst MARKDOWN_EXTENSIONS_PREFIX = 'markdown.extensions.';\n\nconst DEFAULT_ALLOWED_MKDOCS_PLUGINS = new Set([\n 'techdocs-core',\n 'search',\n 'material/search',\n 'redirects',\n 'group',\n 'material/group',\n]);\nconst MKDOCS_PLUGIN_GROUPS = new Set(['group', 'material/group']);\n\n// Plain extension names must be checked against an allowlist rather than\n// passed through: extensions that ship in build images can execute code or\n// load files from the documentation input directory during generation.\nconst DEFAULT_ALLOWED_EXTENSIONS = new Set([\n // Built-in Python-Markdown extensions, bundled with the `markdown` package\n // that both official TechDocs build images ship.\n 'abbr',\n 'admonition',\n 'attr_list',\n 'codehilite',\n 'def_list',\n 'extra',\n 'fenced_code',\n 'footnotes',\n 'legacy_attrs',\n 'legacy_em',\n 'md_in_html',\n 'meta',\n 'nl2br',\n 'sane_lists',\n 'smarty',\n 'tables',\n 'toc',\n 'wikilinks',\n // Rendering extensions shipped in the official TechDocs build images.\n 'markdown_inline_graphviz',\n 'mdx_truly_sane_lists',\n 'plantuml_markdown',\n 'plantuml-markdown',\n // Zensical's rendering extensions. Extensions that load code or files\n // during generation are deliberately not allowed by default.\n 'zensical.extensions.autorefs',\n 'zensical.extensions.context',\n 'zensical.extensions.emoji',\n 'zensical.extensions.glightbox',\n 'zensical.extensions.links',\n]);\n\nfunction isPymdownxSnippetsExtension(extensionName: string): boolean {\n return (\n extensionName === PYMDOWNX_SNIPPETS_EXTENSION ||\n extensionName === `${PYMDOWNX_SNIPPETS_EXTENSION}:SnippetExtension`\n );\n}\n\nfunction isAllowedExtensionName(\n extensionName: string,\n allowedExtensions: Set<string>,\n): boolean {\n // Python-Markdown accepts the full module path for built-in extensions,\n // e.g. markdown.extensions.toc is the same extension as toc.\n const shortName = extensionName.startsWith(MARKDOWN_EXTENSIONS_PREFIX)\n ? extensionName.slice(MARKDOWN_EXTENSIONS_PREFIX.length)\n : extensionName;\n // The pymdownx.* family consists of long-established rendering extensions;\n // the file-including pymdownx.snippets extension is special-cased above.\n return (\n allowedExtensions.has(shortName) ||\n shortName.startsWith(PYMDOWNX_EXTENSION_PREFIX)\n );\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n if (\n typeof value !== 'object' ||\n value === null ||\n Array.isArray(value) ||\n value instanceof UnknownTag\n ) {\n return false;\n }\n\n const prototype = Object.getPrototypeOf(value);\n return prototype === Object.prototype || prototype === null;\n}\n\nfunction normalizeMkdocsPlugins(plugins: unknown): unknown[] | undefined {\n if (Array.isArray(plugins)) {\n return plugins;\n }\n if (isPlainObject(plugins)) {\n return Object.entries(plugins).map(([name, config]) => ({\n [name]: config,\n }));\n }\n return undefined;\n}\n\nfunction sanitizeMkdocsPlugins(\n plugins: unknown,\n allowedPlugins: Set<string>,\n removedPlugins: Set<string>,\n): unknown[] {\n if (plugins instanceof UnknownTag) {\n removedPlugins.add('dynamically configured plugin name');\n return [];\n }\n\n const normalizedPlugins = normalizeMkdocsPlugins(plugins);\n if (!normalizedPlugins) {\n removedPlugins.add('malformed plugin declaration');\n return [];\n }\n\n const sanitizedPlugins: unknown[] = [];\n for (const plugin of normalizedPlugins) {\n if (plugin instanceof UnknownTag) {\n removedPlugins.add('dynamically configured plugin name');\n continue;\n }\n\n let pluginName: string;\n if (typeof plugin === 'string' && plugin.length > 0) {\n pluginName = plugin;\n } else if (isPlainObject(plugin) && Object.keys(plugin).length === 1) {\n [pluginName] = Object.keys(plugin);\n const config = plugin[pluginName];\n if (config !== null && !isPlainObject(config)) {\n removedPlugins.add('malformed plugin declaration');\n continue;\n }\n } else {\n removedPlugins.add('malformed plugin declaration');\n continue;\n }\n\n if (!allowedPlugins.has(pluginName)) {\n removedPlugins.add(pluginName);\n continue;\n }\n\n let sanitizedPlugin = plugin;\n if (isPlainObject(plugin)) {\n const config = plugin[pluginName];\n if (MKDOCS_PLUGIN_GROUPS.has(pluginName) && isPlainObject(config)) {\n sanitizedPlugin = {\n ...plugin,\n [pluginName]: {\n ...config,\n plugins: sanitizeMkdocsPlugins(\n config.plugins,\n allowedPlugins,\n removedPlugins,\n ),\n },\n };\n }\n }\n\n sanitizedPlugins.push(sanitizedPlugin);\n }\n\n return sanitizedPlugins;\n}\n\n// mkdocs-material globs SVGs from every `options.custom_icons` path with no\n// confinement, so the option must be an array of string paths that each\n// resolve inside the documentation input directory, which mkdocs runs from.\nfunction isConfinedCustomIcons(\n customIcons: unknown,\n inputDir: string,\n): boolean {\n if (!Array.isArray(customIcons)) {\n return false;\n }\n\n return customIcons.every(entry => {\n if (typeof entry !== 'string') {\n return false;\n }\n try {\n resolveSafeChildPath(inputDir, entry);\n return true;\n } catch {\n return false;\n }\n });\n}\n\ntype MkDocsThemeObject = {\n name?: string;\n font?: boolean;\n};\n\nfunction isThemeObject(theme: unknown): theme is MkDocsThemeObject {\n return typeof theme === 'object' && theme !== null && !Array.isArray(theme);\n}\n\ntype MkDocsObject = {\n plugins?: string[];\n docs_dir: string;\n repo_url?: string;\n edit_uri?: string;\n theme?: MkDocsThemeObject;\n};\n\nconst patchMkdocsFile = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n updateAction: (mkdocsYml: MkDocsObject) => boolean,\n options?: { failOnError?: boolean },\n) => {\n // We only want to override the mkdocs.yml if it has actually changed. This is relevant if\n // used with a 'dir' location on the file system as this would permanently update the file.\n let didEdit = false;\n\n let mkdocsYmlFileString;\n try {\n mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');\n } catch (error) {\n logger.warn(\n `Could not read MkDocs YAML config file ${mkdocsYmlPath} before running the generator: ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n\n let mkdocsYml: any;\n try {\n mkdocsYml = yaml.load(mkdocsYmlFileString, { schema: MKDOCS_SCHEMA });\n\n // mkdocsYml should be an object type after successful parsing.\n // But based on its type definition, it can also be a string or undefined, which we don't want.\n if (typeof mkdocsYml === 'string' || typeof mkdocsYml === 'undefined') {\n throw new Error('Bad YAML format.');\n }\n } catch (error) {\n logger.warn(\n `Error in parsing YAML at ${mkdocsYmlPath} before running the generator. ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n\n didEdit = updateAction(mkdocsYml);\n\n try {\n if (didEdit) {\n await fs.writeFile(\n mkdocsYmlPath,\n yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),\n 'utf8',\n );\n }\n } catch (error) {\n logger.warn(\n `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${\n toError(error).message\n }`,\n );\n if (options?.failOnError) {\n throw error;\n }\n return;\n }\n};\n\nconst patchMkdocsFileOrThrow = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n updateAction: (mkdocsYml: MkDocsObject) => boolean,\n) =>\n patchMkdocsFile(mkdocsYmlPath, logger, updateAction, {\n failOnError: true,\n });\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add repo_url or edit_uri if it does not exists\n * If mkdocs.yml has a repo_url, the generated docs site gets an Edit button on the pages by default.\n * If repo_url is missing in mkdocs.yml, we will use techdocs annotation of the entity to possibly get\n * the repository URL.\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param parsedLocationAnnotation - Object with location url and type\n * @param scmIntegrations - the scmIntegration to do url transformations\n */\nexport const patchMkdocsYmlPreBuild = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n parsedLocationAnnotation: ParsedLocationAnnotation,\n scmIntegrations: ScmIntegrationRegistry,\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n if (!('repo_url' in mkdocsYml) || !('edit_uri' in mkdocsYml)) {\n // Add edit_uri and/or repo_url to mkdocs.yml if it is missing.\n // This will enable the Page edit button generated by MkDocs.\n // If the either has been set, keep the original value\n const result = getRepoUrlFromLocationAnnotation(\n parsedLocationAnnotation,\n scmIntegrations,\n mkdocsYml.docs_dir,\n );\n\n if (result.repo_url || result.edit_uri) {\n mkdocsYml.repo_url = mkdocsYml.repo_url || result.repo_url;\n mkdocsYml.edit_uri = mkdocsYml.edit_uri || result.edit_uri;\n\n logger.info(\n `Set ${JSON.stringify(\n result,\n )}. You can disable this feature by manually setting 'repo_url' or 'edit_uri' according to the MkDocs documentation at https://www.mkdocs.org/user-guide/configuration/#repo_url`,\n );\n return true;\n }\n }\n return false;\n });\n};\n\n/**\n * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site.\n *\n * List of tasks:\n * - Add all provided default plugins\n *\n * This function will not throw an error since this is not critical to the whole TechDocs pipeline.\n * Instead it will log warnings if there are any errors in reading, parsing or writing YAML.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param defaultPlugins - List of default mkdocs plugins\n */\nexport const patchMkdocsYmlWithPlugins = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n defaultPlugins: string[] = ['techdocs-core'],\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n // Modify mkdocs.yaml to contain the required default plugins.\n // If no plugins are defined we can just return the defaults.\n if (!('plugins' in mkdocsYml)) {\n mkdocsYml.plugins = defaultPlugins;\n return true;\n }\n\n // Otherwise, check each default plugin and include it if necessary.\n let changesMade = false;\n\n defaultPlugins.forEach(dp => {\n // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)\n // then we need to add it\n if (\n !(\n mkdocsYml.plugins!.includes(dp) ||\n mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))\n )\n ) {\n mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];\n changesMade = true;\n }\n });\n\n return changesMade;\n });\n};\n\n/**\n * Disable external font download for the material theme.\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger\n */\nexport const patchMkdocsYmlWithFontDisabled = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n) => {\n await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {\n if (!('theme' in mkdocsYml)) {\n // No theme section exists, create it with font disabled\n mkdocsYml.theme = {\n name: MATERIAL_THEME,\n font: false,\n };\n return true;\n }\n\n const theme = mkdocsYml.theme;\n if (isThemeObject(theme)) {\n // Theme section exists. Only modify it when the configured theme is Material\n if (theme.name === MATERIAL_THEME && !('font' in theme)) {\n theme.font = false;\n return true;\n }\n if (theme.name !== MATERIAL_THEME) {\n logger.debug(\n 'mkdocs.yml theme is not \"material\"; skipping font disabling patch',\n );\n }\n }\n\n return false;\n });\n};\n\n/**\n * Sanitize mkdocs.yml by keeping only allowed configuration keys.\n *\n * TechDocs only supports a subset of MkDocs configuration options.\n * This function reconstructs the config with only allowed keys,\n * discarding everything else. This approach ensures that any unknown\n * or potentially dangerous configuration options are not passed to MkDocs.\n *\n * The file is always rewritten to ensure YAML features like merge keys\n * and anchors are resolved into plain configuration.\n *\n * @param mkdocsYmlPath - Absolute path to mkdocs.yml or equivalent of a docs site\n * @param logger - A logger instance\n * @param additionalAllowedKeys - Optional array of additional keys to allow beyond the default allowlist\n * @param additionalAllowedPlugins - Optional array of additional plugins to allow beyond the default set\n * @param additionalAllowedExtensions - Optional array of additional markdown extensions to allow beyond the default set\n * @alpha\n */\nexport const sanitizeMkdocsYml = async (\n mkdocsYmlPath: string,\n logger: LoggerService,\n additionalAllowedKeys?: string[],\n additionalAllowedPlugins?: string[],\n additionalAllowedExtensions?: string[],\n) => {\n await patchMkdocsFileOrThrow(mkdocsYmlPath, logger, mkdocsYml => {\n // Combine default allowed keys with additional keys\n const allowedKeys = new Set(ALLOWED_MKDOCS_KEYS);\n if (additionalAllowedKeys && additionalAllowedKeys.length > 0) {\n logger.warn(\n `DANGEROUS: Allowing additional MkDocs configuration keys beyond the default safe allowlist: ${additionalAllowedKeys.join(\n ', ',\n )}. This may introduce security vulnerabilities. Only use in trusted environments.`,\n );\n additionalAllowedKeys.forEach(key => allowedKeys.add(key));\n }\n\n const allowedExtensions = new Set(DEFAULT_ALLOWED_EXTENSIONS);\n if (additionalAllowedExtensions && additionalAllowedExtensions.length > 0) {\n logger.warn(\n `DANGEROUS: Allowing additional MkDocs markdown extensions beyond the default safe allowlist: ${additionalAllowedExtensions.join(\n ', ',\n )}. Some markdown extensions execute code or load files from the documentation input directory. Only use in trusted environments.`,\n );\n additionalAllowedExtensions.forEach(extension =>\n allowedExtensions.add(extension),\n );\n }\n\n // Identify keys that will be removed for logging\n const removedKeys = Object.keys(mkdocsYml).filter(\n key => !allowedKeys.has(key),\n );\n\n if (removedKeys.length > 0) {\n logger.warn(\n `Removed the following unsupported configuration keys from mkdocs.yml: ${removedKeys.join(\n ', ',\n )}. ` +\n `TechDocs only supports a subset of MkDocs configuration options.`,\n );\n }\n\n // Build a new object with only allowed keys\n const sanitized: Record<string, unknown> = {};\n for (const key of allowedKeys) {\n if (key in mkdocsYml) {\n sanitized[key] = (mkdocsYml as Record<string, unknown>)[key];\n }\n }\n\n // Sanitize markdown_extensions\n const extensions = sanitized.markdown_extensions;\n const removedEntries: string[] = [];\n const inputDir = path.dirname(mkdocsYmlPath);\n let removedCustomIcons = false;\n const extensionMapping = isPlainObject(extensions) ? extensions : undefined;\n let normalizedExtensions: unknown[] | undefined;\n if (Array.isArray(extensions)) {\n normalizedExtensions = extensions;\n } else if (extensionMapping) {\n normalizedExtensions = Object.entries(extensionMapping).map(\n ([name, config]) => ({\n [name]: config,\n }),\n );\n }\n if (extensions instanceof UnknownTag) {\n removedEntries.push('dynamically configured extension');\n sanitized.markdown_extensions = [];\n } else if (normalizedExtensions) {\n const sanitizedExtensions = normalizedExtensions.flatMap<unknown>(ext => {\n if (ext instanceof UnknownTag) {\n removedEntries.push('dynamically configured extension');\n return [];\n }\n\n if (typeof ext === 'string') {\n if (isPymdownxSnippetsExtension(ext)) {\n return [ext];\n }\n\n if (ext.includes(':')) {\n removedEntries.push(ext);\n return [];\n }\n\n if (!isAllowedExtensionName(ext, allowedExtensions)) {\n removedEntries.push(ext);\n return [];\n }\n return [ext];\n }\n\n if (!isPlainObject(ext)) {\n removedEntries.push('malformed extension declaration');\n return [];\n }\n\n // Check every key, not just the first, so that a multi-key mapping\n // cannot smuggle a dangerous name past the filter.\n const extensionEntries = Object.entries(ext);\n const dangerousNames = extensionEntries\n .map(([extensionName]) => extensionName)\n .filter(\n extensionName =>\n extensionName.includes(':') &&\n !isPymdownxSnippetsExtension(extensionName),\n );\n if (dangerousNames.length > 0) {\n removedEntries.push(...dangerousNames);\n return [];\n }\n\n const sanitizedExtension: Record<string, unknown> = {};\n for (const [extensionName, extensionConfig] of extensionEntries) {\n if (!isAllowedExtensionName(extensionName, allowedExtensions)) {\n removedEntries.push(extensionName);\n continue;\n }\n\n if (extensionConfig instanceof UnknownTag) {\n removedEntries.push(\n `dynamically configured ${extensionName} extension`,\n );\n continue;\n }\n\n if (isPymdownxSnippetsExtension(extensionName)) {\n if (\n extensionConfig !== null &&\n (typeof extensionConfig !== 'object' ||\n Object.keys(extensionConfig).length > 0)\n ) {\n removedEntries.push(`${extensionName} configuration`);\n }\n sanitizedExtension[extensionName] = {};\n } else if (isPlainObject(extensionConfig)) {\n const sanitizedConfig = { ...extensionConfig };\n for (const dangerousKey of DANGEROUS_EXTENSION_CONFIG_KEYS) {\n if (dangerousKey in sanitizedConfig) {\n delete sanitizedConfig[dangerousKey];\n removedEntries.push(dangerousKey);\n }\n }\n\n const options = sanitizedConfig.options;\n // A tagged value such as `!ENV` resolves to a mapping at build\n // time, so its custom_icons cannot be checked here.\n if (options instanceof UnknownTag) {\n delete sanitizedConfig.options;\n removedCustomIcons = true;\n } else if (isPlainObject(options) && 'custom_icons' in options) {\n if (!isConfinedCustomIcons(options.custom_icons, inputDir)) {\n const sanitizedOptions = { ...options };\n delete sanitizedOptions.custom_icons;\n sanitizedConfig.options = sanitizedOptions;\n removedCustomIcons = true;\n }\n }\n sanitizedExtension[extensionName] = sanitizedConfig;\n } else {\n sanitizedExtension[extensionName] = extensionConfig;\n }\n }\n\n return Object.keys(sanitizedExtension).length > 0\n ? [sanitizedExtension]\n : [];\n });\n\n sanitized.markdown_extensions = extensionMapping\n ? Object.assign({}, ...sanitizedExtensions)\n : sanitizedExtensions;\n } else if (extensions !== undefined) {\n removedEntries.push('malformed extension declaration');\n sanitized.markdown_extensions = [];\n }\n\n if (removedEntries.length > 0) {\n logger.warn(\n `Removed the following dangerous or unsupported entries from markdown_extensions in mkdocs.yml: ${removedEntries.join(\n ', ',\n )}. To allow additional markdown extensions, configure 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalExtensions' in your Backstage app-config. When using the TechDocs CLI, use '--dangerouslyAllowAdditionalExtensions' instead.`,\n );\n }\n\n if (removedCustomIcons) {\n logger.warn(\n `Removed the custom_icons option from markdown_extensions in mkdocs.yml because it must be an array of string paths inside the documentation input directory.`,\n );\n }\n\n if ('plugins' in sanitized) {\n const allowedPlugins = new Set(DEFAULT_ALLOWED_MKDOCS_PLUGINS);\n additionalAllowedPlugins?.forEach(plugin => allowedPlugins.add(plugin));\n\n const removedPlugins = new Set<string>();\n sanitized.plugins = sanitizeMkdocsPlugins(\n sanitized.plugins,\n allowedPlugins,\n removedPlugins,\n );\n\n if (removedPlugins.size > 0) {\n logger.warn(\n `Removed unsupported MkDocs plugins from mkdocs.yml: ${Array.from(\n removedPlugins,\n ).join(\n ', ',\n )}. To allow additional plugins, configure 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins' in your Backstage app-config. When using the TechDocs CLI, use '--defaultPlugin' instead.`,\n );\n }\n }\n\n // Clear the original object and copy sanitized values back\n for (const key of Object.keys(mkdocsYml)) {\n delete (mkdocsYml as Record<string, unknown>)[key];\n }\n Object.assign(mkdocsYml, sanitized);\n\n // Sanitize theme sub-keys\n const theme = (mkdocsYml as Record<string, unknown>).theme;\n if (isThemeObject(theme)) {\n const removedThemeKeys = Object.keys(theme).filter(\n key => !ALLOWED_THEME_KEYS.has(key),\n );\n if (removedThemeKeys.length > 0) {\n for (const key of removedThemeKeys) {\n delete (theme as Record<string, unknown>)[key];\n }\n logger.warn(\n `Removed the following unsupported keys from theme configuration in mkdocs.yml: ${removedThemeKeys.join(\n ', ',\n )}.`,\n );\n }\n }\n\n // Always rewrite to ensure clean YAML output (resolves merge keys, anchors, etc.)\n return true;\n });\n};\n"],"names":["UnknownTag","resolveSafeChildPath","fs","toError","yaml","MKDOCS_SCHEMA","getRepoUrlFromLocationAnnotation","ALLOWED_MKDOCS_KEYS","path","DANGEROUS_EXTENSION_CONFIG_KEYS","ALLOWED_THEME_KEYS"],"mappings":"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"}
|
|
@@ -79,7 +79,8 @@ class TechdocsGenerator {
|
|
|
79
79
|
[
|
|
80
80
|
...this.options.dangerouslyAllowAdditionalPlugins ?? [],
|
|
81
81
|
...defaultPlugins
|
|
82
|
-
]
|
|
82
|
+
],
|
|
83
|
+
this.options.dangerouslyAllowAdditionalExtensions
|
|
83
84
|
);
|
|
84
85
|
if (parsedLocationAnnotation) {
|
|
85
86
|
await mkdocsPatchers.patchMkdocsYmlPreBuild(
|
|
@@ -210,6 +211,9 @@ function readGeneratorConfig(config, logger) {
|
|
|
210
211
|
dangerouslyAllowAdditionalPlugins: config.getOptionalStringArray(
|
|
211
212
|
"techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins"
|
|
212
213
|
),
|
|
214
|
+
dangerouslyAllowAdditionalExtensions: config.getOptionalStringArray(
|
|
215
|
+
"techdocs.generator.mkdocs.dangerouslyAllowAdditionalExtensions"
|
|
216
|
+
),
|
|
213
217
|
disableExternalFonts: config.getOptionalBoolean(
|
|
214
218
|
"techdocs.generator.mkdocs.disableExternalFonts"
|
|
215
219
|
)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"techdocs.cjs.js","sources":["../../../src/stages/generate/techdocs.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport fs from 'fs-extra';\nimport path from 'node:path';\nimport {\n ScmIntegrationRegistry,\n ScmIntegrations,\n} from '@backstage/integration';\nimport {\n createOrUpdateMetadata,\n getMkdocsYml,\n patchIndexPreBuild,\n runCommand,\n storeEtagMetadata,\n validateInputDirectory,\n validateMkdocsYaml,\n} from './helpers';\n\nimport {\n patchMkdocsYmlPreBuild,\n patchMkdocsYmlWithFontDisabled,\n patchMkdocsYmlWithPlugins,\n sanitizeMkdocsYml,\n} from './mkdocsPatchers';\nimport {\n ContainerRunnerPullOptions,\n GeneratorBase,\n GeneratorConfig,\n GeneratorOptions,\n GeneratorRunInType,\n GeneratorRunOptions,\n} from './types';\nimport { ForwardedError } from '@backstage/errors';\nimport { DockerContainerRunner } from './DockerContainerRunner';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Generates documentation files\n * @public\n */\nexport class TechdocsGenerator implements GeneratorBase {\n /**\n * The default docker image (and version) used to generate content. Public\n * and static so that techdocs-node consumers can use the same version.\n *\n * See {@link https://hub.docker.com/r/spotify/techdocs/tags} for list of available versions.\n */\n public static readonly defaultDockerImage = 'spotify/techdocs:v1.2.8';\n private readonly logger: LoggerService;\n private readonly containerRunner?: TechDocsContainerRunner;\n private readonly options: GeneratorConfig;\n private readonly scmIntegrations: ScmIntegrationRegistry;\n\n /**\n * Returns a instance of TechDocs generator\n * @param config - A Backstage configuration\n * @param options - Options to configure the generator\n */\n static fromConfig(config: Config, options: GeneratorOptions) {\n const { containerRunner, logger } = options;\n const scmIntegrations = ScmIntegrations.fromConfig(config);\n return new TechdocsGenerator({\n logger,\n containerRunner,\n config,\n scmIntegrations,\n });\n }\n\n constructor(options: {\n logger: LoggerService;\n containerRunner?: TechDocsContainerRunner;\n config: Config;\n scmIntegrations: ScmIntegrationRegistry;\n }) {\n this.logger = options.logger;\n this.options = readGeneratorConfig(options.config, options.logger);\n this.containerRunner = options.containerRunner;\n this.scmIntegrations = options.scmIntegrations;\n }\n\n /** {@inheritDoc GeneratorBase.run} */\n public async run(options: GeneratorRunOptions): Promise<void> {\n const {\n inputDir,\n outputDir,\n parsedLocationAnnotation,\n etag,\n logger: childLogger,\n logStream,\n siteOptions,\n runAsDefaultUser,\n } = options;\n\n // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url\n const { path: mkdocsYmlPath, content } = await getMkdocsYml(\n inputDir,\n siteOptions,\n );\n\n // Warn if both config files exist — MkDocs and Backstage resolve them in\n // different order, so a second file would be silently ignored by one side.\n const alternateConfigName =\n path.basename(mkdocsYmlPath) === 'mkdocs.yaml'\n ? 'mkdocs.yml'\n : 'mkdocs.yaml';\n if (await fs.pathExists(path.join(inputDir, alternateConfigName))) {\n childLogger.warn(\n `Both mkdocs.yml and mkdocs.yaml found in ${inputDir}; using ${path.basename(\n mkdocsYmlPath,\n )}. The other file will be ignored.`,\n );\n }\n\n // validate the docs_dir first\n const docsDir = await validateMkdocsYaml(inputDir, content);\n\n const defaultPlugins = [...(this.options.defaultPlugins ?? [])];\n\n // Remove unsupported configuration keys and plugins\n await sanitizeMkdocsYml(\n mkdocsYmlPath,\n childLogger,\n this.options.dangerouslyAllowAdditionalKeys,\n [\n ...(this.options.dangerouslyAllowAdditionalPlugins ?? []),\n ...defaultPlugins,\n ],\n );\n\n if (parsedLocationAnnotation) {\n await patchMkdocsYmlPreBuild(\n mkdocsYmlPath,\n childLogger,\n parsedLocationAnnotation,\n this.scmIntegrations,\n );\n }\n\n if (this.options.legacyCopyReadmeMdToIndexMd) {\n await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });\n }\n\n // Validate that no symlinks in the input directory point outside it. MkDocs\n // extensions can access files throughout the input directory, not just docs_dir.\n await validateInputDirectory(inputDir);\n\n // patch the list of mkdocs plugins\n if (\n !this.options.omitTechdocsCoreMkdocsPlugin &&\n !defaultPlugins.includes('techdocs-core')\n ) {\n defaultPlugins.push('techdocs-core');\n }\n\n await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);\n if (this.options.disableExternalFonts) {\n await patchMkdocsYmlWithFontDisabled(mkdocsYmlPath, childLogger);\n }\n\n // Directories to bind on container\n const mountDirs = {\n [inputDir]: '/input',\n [outputDir]: '/output',\n };\n\n try {\n switch (this.options.runIn) {\n case 'local':\n await runCommand({\n command: 'mkdocs',\n args: [\n 'build',\n '-f',\n path.relative(inputDir, mkdocsYmlPath),\n '-d',\n outputDir,\n '-v',\n ],\n options: {\n cwd: inputDir,\n },\n logStream,\n });\n childLogger.info(\n `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,\n );\n break;\n case 'docker': {\n const containerRunner =\n this.containerRunner || new DockerContainerRunner();\n await containerRunner.runContainer({\n imageName:\n this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,\n args: [\n 'build',\n '-f',\n `/input/${path.basename(mkdocsYmlPath)}`,\n '-d',\n '/output',\n ],\n logStream,\n mountDirs,\n workingDir: '/input',\n // Set the home directory inside the container as something that applications can\n // write to, otherwise they will just fail trying to write to /\n envVars: { HOME: '/tmp' },\n pullImage: this.options.pullImage,\n pullOptions: this.options.pullOptions,\n defaultUser: runAsDefaultUser,\n });\n childLogger.info(\n `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,\n );\n break;\n }\n default:\n throw new Error(\n `Invalid config value \"${this.options.runIn}\" provided in 'techdocs.generators.techdocs'.`,\n );\n }\n } catch (error) {\n this.logger.debug(\n `Failed to generate docs from ${inputDir} into ${outputDir}`,\n );\n throw new ForwardedError(\n `Failed to generate docs from ${inputDir} into ${outputDir}`,\n error,\n );\n }\n\n /**\n * Post Generate steps\n */\n\n // Add build timestamp and files to techdocs_metadata.json\n // Creates techdocs_metadata.json if file does not exist.\n await createOrUpdateMetadata(\n path.join(outputDir, 'techdocs_metadata.json'),\n childLogger,\n 'mkdocs',\n );\n\n // Add etag of the prepared tree to techdocs_metadata.json\n // Assumes that the file already exists.\n if (etag) {\n await storeEtagMetadata(\n path.join(outputDir, 'techdocs_metadata.json'),\n etag,\n );\n }\n }\n}\n\nexport function readGeneratorConfig(\n config: Config,\n logger: LoggerService,\n): GeneratorConfig {\n const legacyGeneratorType = config.getOptionalString(\n 'techdocs.generators.techdocs',\n ) as GeneratorRunInType;\n\n if (legacyGeneratorType) {\n logger.warn(\n `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +\n `See here https://backstage.io/docs/features/techdocs/configuration`,\n );\n }\n\n return {\n runIn:\n legacyGeneratorType ??\n config.getOptionalString('techdocs.generator.runIn') ??\n 'docker',\n dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),\n pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),\n pullOptions: config.getOptional<ContainerRunnerPullOptions>(\n 'techdocs.generator.pullOptions',\n ),\n omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.omitTechdocsCorePlugin',\n ),\n legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',\n ),\n defaultPlugins: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.defaultPlugins',\n ),\n dangerouslyAllowAdditionalKeys: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys',\n ),\n dangerouslyAllowAdditionalPlugins: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins',\n ),\n disableExternalFonts: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.disableExternalFonts',\n ),\n };\n}\n"],"names":["ScmIntegrations","getMkdocsYml","path","fs","validateMkdocsYaml","sanitizeMkdocsYml","patchMkdocsYmlPreBuild","patchIndexPreBuild","validateInputDirectory","patchMkdocsYmlWithPlugins","patchMkdocsYmlWithFontDisabled","runCommand","DockerContainerRunner","ForwardedError","createOrUpdateMetadata","storeEtagMetadata"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"techdocs.cjs.js","sources":["../../../src/stages/generate/techdocs.ts"],"sourcesContent":["/*\n * Copyright 2020 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Config } from '@backstage/config';\nimport fs from 'fs-extra';\nimport path from 'node:path';\nimport {\n ScmIntegrationRegistry,\n ScmIntegrations,\n} from '@backstage/integration';\nimport {\n createOrUpdateMetadata,\n getMkdocsYml,\n patchIndexPreBuild,\n runCommand,\n storeEtagMetadata,\n validateInputDirectory,\n validateMkdocsYaml,\n} from './helpers';\n\nimport {\n patchMkdocsYmlPreBuild,\n patchMkdocsYmlWithFontDisabled,\n patchMkdocsYmlWithPlugins,\n sanitizeMkdocsYml,\n} from './mkdocsPatchers';\nimport {\n ContainerRunnerPullOptions,\n GeneratorBase,\n GeneratorConfig,\n GeneratorOptions,\n GeneratorRunInType,\n GeneratorRunOptions,\n} from './types';\nimport { ForwardedError } from '@backstage/errors';\nimport { DockerContainerRunner } from './DockerContainerRunner';\nimport { LoggerService } from '@backstage/backend-plugin-api';\nimport { TechDocsContainerRunner } from './types';\n\n/**\n * Generates documentation files\n * @public\n */\nexport class TechdocsGenerator implements GeneratorBase {\n /**\n * The default docker image (and version) used to generate content. Public\n * and static so that techdocs-node consumers can use the same version.\n *\n * See {@link https://hub.docker.com/r/spotify/techdocs/tags} for list of available versions.\n */\n public static readonly defaultDockerImage = 'spotify/techdocs:v1.2.8';\n private readonly logger: LoggerService;\n private readonly containerRunner?: TechDocsContainerRunner;\n private readonly options: GeneratorConfig;\n private readonly scmIntegrations: ScmIntegrationRegistry;\n\n /**\n * Returns a instance of TechDocs generator\n * @param config - A Backstage configuration\n * @param options - Options to configure the generator\n */\n static fromConfig(config: Config, options: GeneratorOptions) {\n const { containerRunner, logger } = options;\n const scmIntegrations = ScmIntegrations.fromConfig(config);\n return new TechdocsGenerator({\n logger,\n containerRunner,\n config,\n scmIntegrations,\n });\n }\n\n constructor(options: {\n logger: LoggerService;\n containerRunner?: TechDocsContainerRunner;\n config: Config;\n scmIntegrations: ScmIntegrationRegistry;\n }) {\n this.logger = options.logger;\n this.options = readGeneratorConfig(options.config, options.logger);\n this.containerRunner = options.containerRunner;\n this.scmIntegrations = options.scmIntegrations;\n }\n\n /** {@inheritDoc GeneratorBase.run} */\n public async run(options: GeneratorRunOptions): Promise<void> {\n const {\n inputDir,\n outputDir,\n parsedLocationAnnotation,\n etag,\n logger: childLogger,\n logStream,\n siteOptions,\n runAsDefaultUser,\n } = options;\n\n // Do some updates to mkdocs.yml before generating docs e.g. adding repo_url\n const { path: mkdocsYmlPath, content } = await getMkdocsYml(\n inputDir,\n siteOptions,\n );\n\n // Warn if both config files exist — MkDocs and Backstage resolve them in\n // different order, so a second file would be silently ignored by one side.\n const alternateConfigName =\n path.basename(mkdocsYmlPath) === 'mkdocs.yaml'\n ? 'mkdocs.yml'\n : 'mkdocs.yaml';\n if (await fs.pathExists(path.join(inputDir, alternateConfigName))) {\n childLogger.warn(\n `Both mkdocs.yml and mkdocs.yaml found in ${inputDir}; using ${path.basename(\n mkdocsYmlPath,\n )}. The other file will be ignored.`,\n );\n }\n\n // validate the docs_dir first\n const docsDir = await validateMkdocsYaml(inputDir, content);\n\n const defaultPlugins = [...(this.options.defaultPlugins ?? [])];\n\n // Remove unsupported configuration keys and plugins\n await sanitizeMkdocsYml(\n mkdocsYmlPath,\n childLogger,\n this.options.dangerouslyAllowAdditionalKeys,\n [\n ...(this.options.dangerouslyAllowAdditionalPlugins ?? []),\n ...defaultPlugins,\n ],\n this.options.dangerouslyAllowAdditionalExtensions,\n );\n\n if (parsedLocationAnnotation) {\n await patchMkdocsYmlPreBuild(\n mkdocsYmlPath,\n childLogger,\n parsedLocationAnnotation,\n this.scmIntegrations,\n );\n }\n\n if (this.options.legacyCopyReadmeMdToIndexMd) {\n await patchIndexPreBuild({ inputDir, logger: childLogger, docsDir });\n }\n\n // Validate that no symlinks in the input directory point outside it. MkDocs\n // extensions can access files throughout the input directory, not just docs_dir.\n await validateInputDirectory(inputDir);\n\n // patch the list of mkdocs plugins\n if (\n !this.options.omitTechdocsCoreMkdocsPlugin &&\n !defaultPlugins.includes('techdocs-core')\n ) {\n defaultPlugins.push('techdocs-core');\n }\n\n await patchMkdocsYmlWithPlugins(mkdocsYmlPath, childLogger, defaultPlugins);\n if (this.options.disableExternalFonts) {\n await patchMkdocsYmlWithFontDisabled(mkdocsYmlPath, childLogger);\n }\n\n // Directories to bind on container\n const mountDirs = {\n [inputDir]: '/input',\n [outputDir]: '/output',\n };\n\n try {\n switch (this.options.runIn) {\n case 'local':\n await runCommand({\n command: 'mkdocs',\n args: [\n 'build',\n '-f',\n path.relative(inputDir, mkdocsYmlPath),\n '-d',\n outputDir,\n '-v',\n ],\n options: {\n cwd: inputDir,\n },\n logStream,\n });\n childLogger.info(\n `Successfully generated docs from ${inputDir} into ${outputDir} using local mkdocs`,\n );\n break;\n case 'docker': {\n const containerRunner =\n this.containerRunner || new DockerContainerRunner();\n await containerRunner.runContainer({\n imageName:\n this.options.dockerImage ?? TechdocsGenerator.defaultDockerImage,\n args: [\n 'build',\n '-f',\n `/input/${path.basename(mkdocsYmlPath)}`,\n '-d',\n '/output',\n ],\n logStream,\n mountDirs,\n workingDir: '/input',\n // Set the home directory inside the container as something that applications can\n // write to, otherwise they will just fail trying to write to /\n envVars: { HOME: '/tmp' },\n pullImage: this.options.pullImage,\n pullOptions: this.options.pullOptions,\n defaultUser: runAsDefaultUser,\n });\n childLogger.info(\n `Successfully generated docs from ${inputDir} into ${outputDir} using techdocs-container`,\n );\n break;\n }\n default:\n throw new Error(\n `Invalid config value \"${this.options.runIn}\" provided in 'techdocs.generators.techdocs'.`,\n );\n }\n } catch (error) {\n this.logger.debug(\n `Failed to generate docs from ${inputDir} into ${outputDir}`,\n );\n throw new ForwardedError(\n `Failed to generate docs from ${inputDir} into ${outputDir}`,\n error,\n );\n }\n\n /**\n * Post Generate steps\n */\n\n // Add build timestamp and files to techdocs_metadata.json\n // Creates techdocs_metadata.json if file does not exist.\n await createOrUpdateMetadata(\n path.join(outputDir, 'techdocs_metadata.json'),\n childLogger,\n 'mkdocs',\n );\n\n // Add etag of the prepared tree to techdocs_metadata.json\n // Assumes that the file already exists.\n if (etag) {\n await storeEtagMetadata(\n path.join(outputDir, 'techdocs_metadata.json'),\n etag,\n );\n }\n }\n}\n\nexport function readGeneratorConfig(\n config: Config,\n logger: LoggerService,\n): GeneratorConfig {\n const legacyGeneratorType = config.getOptionalString(\n 'techdocs.generators.techdocs',\n ) as GeneratorRunInType;\n\n if (legacyGeneratorType) {\n logger.warn(\n `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +\n `See here https://backstage.io/docs/features/techdocs/configuration`,\n );\n }\n\n return {\n runIn:\n legacyGeneratorType ??\n config.getOptionalString('techdocs.generator.runIn') ??\n 'docker',\n dockerImage: config.getOptionalString('techdocs.generator.dockerImage'),\n pullImage: config.getOptionalBoolean('techdocs.generator.pullImage'),\n pullOptions: config.getOptional<ContainerRunnerPullOptions>(\n 'techdocs.generator.pullOptions',\n ),\n omitTechdocsCoreMkdocsPlugin: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.omitTechdocsCorePlugin',\n ),\n legacyCopyReadmeMdToIndexMd: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd',\n ),\n defaultPlugins: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.defaultPlugins',\n ),\n dangerouslyAllowAdditionalKeys: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys',\n ),\n dangerouslyAllowAdditionalPlugins: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalPlugins',\n ),\n dangerouslyAllowAdditionalExtensions: config.getOptionalStringArray(\n 'techdocs.generator.mkdocs.dangerouslyAllowAdditionalExtensions',\n ),\n disableExternalFonts: config.getOptionalBoolean(\n 'techdocs.generator.mkdocs.disableExternalFonts',\n ),\n };\n}\n"],"names":["ScmIntegrations","getMkdocsYml","path","fs","validateMkdocsYaml","sanitizeMkdocsYml","patchMkdocsYmlPreBuild","patchIndexPreBuild","validateInputDirectory","patchMkdocsYmlWithPlugins","patchMkdocsYmlWithFontDisabled","runCommand","DockerContainerRunner","ForwardedError","createOrUpdateMetadata","storeEtagMetadata"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@backstage/plugin-techdocs-node",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.0",
|
|
4
4
|
"description": "Common node.js functionalities for TechDocs, to be shared between techdocs-backend plugin and techdocs-cli",
|
|
5
5
|
"backstage": {
|
|
6
6
|
"role": "node-library",
|
|
@@ -74,14 +74,14 @@
|
|
|
74
74
|
"@aws-sdk/types": "^3.347.0",
|
|
75
75
|
"@azure/identity": "^4.0.0",
|
|
76
76
|
"@azure/storage-blob": "^12.5.0",
|
|
77
|
-
"@backstage/backend-plugin-api": "1.12.0
|
|
78
|
-
"@backstage/catalog-model": "1.10.3
|
|
79
|
-
"@backstage/config": "1.3.11
|
|
80
|
-
"@backstage/errors": "1.4.0
|
|
81
|
-
"@backstage/integration": "2.
|
|
82
|
-
"@backstage/integration-aws-node": "0.2.4
|
|
83
|
-
"@backstage/plugin-search-common": "1.2.27
|
|
84
|
-
"@backstage/plugin-techdocs-common": "0.1.3
|
|
77
|
+
"@backstage/backend-plugin-api": "^1.12.0",
|
|
78
|
+
"@backstage/catalog-model": "^1.10.3",
|
|
79
|
+
"@backstage/config": "^1.3.11",
|
|
80
|
+
"@backstage/errors": "^1.4.0",
|
|
81
|
+
"@backstage/integration": "^2.2.0",
|
|
82
|
+
"@backstage/integration-aws-node": "^0.2.4",
|
|
83
|
+
"@backstage/plugin-search-common": "^1.2.27",
|
|
84
|
+
"@backstage/plugin-techdocs-common": "^0.1.3",
|
|
85
85
|
"@google-cloud/storage": "^7.0.0",
|
|
86
86
|
"@smithy/node-http-handler": "^3.0.0",
|
|
87
87
|
"@trendyol-js/openstack-swift-sdk": "^0.0.7",
|
|
@@ -100,8 +100,8 @@
|
|
|
100
100
|
"winston": "^3.2.1"
|
|
101
101
|
},
|
|
102
102
|
"devDependencies": {
|
|
103
|
-
"@backstage/backend-test-utils": "1.12.0
|
|
104
|
-
"@backstage/cli": "0.36.8
|
|
103
|
+
"@backstage/backend-test-utils": "^1.12.0",
|
|
104
|
+
"@backstage/cli": "^0.36.8",
|
|
105
105
|
"@types/fs-extra": "^11.0.0",
|
|
106
106
|
"@types/mime-types": "^2.1.0",
|
|
107
107
|
"@types/recursive-readdir": "^2.2.0",
|