Merge remote-tracking branch 'upstream/master' into feat/relative-ref-tmp

packages/techdocs-common/src/stages/generate/__fixtures__/mkdocs_valid_doc_dir.yml

@@ -0,0 +1,3 @@
+site_name: Test site name
+site_description: Test site description
+docs_dir: docs/

packages/techdocs-common/src/stages/generate/helpers.test.ts

@@ -47,6 +47,9 @@ const mkdocsYmlWithExtensions = fs.readFileSync(
 const mkdocsYmlWithRepoUrl = fs.readFileSync(
   resolvePath(__filename, '../__fixtures__/mkdocs_with_repo_url.yml'),
 );
+const mkdocsYmlWithValidDocDir = fs.readFileSync(
+  resolvePath(__filename, '../__fixtures__/mkdocs_valid_doc_dir.yml'),
+);
 const mkdocsYmlWithInvalidDocDir = fs.readFileSync(
   resolvePath(__filename, '../__fixtures__/mkdocs_invalid_doc_dir.yml'),
 );
@@ -336,6 +339,7 @@ describe('helpers', () => {
       mockFs({
         '/mkdocs.yml': mkdocsYml,
         '/mkdocs_with_extensions.yml': mkdocsYmlWithExtensions,
+        '/mkdocs_valid_doc_dir.yml': mkdocsYmlWithValidDocDir,
         '/mkdocs_invalid_doc_dir.yml': mkdocsYmlWithInvalidDocDir,
       });
     });
@@ -351,6 +355,12 @@ describe('helpers', () => {
       ).resolves.toBeUndefined();
     });
 
+    it('should return true on when a valid docs_dir is present', async () => {
+      await expect(
+        validateMkdocsYaml(inputDir, '/mkdocs_valid_doc_dir.yml'),
+      ).resolves.toBeUndefined();
+    });
+
     it('should return false on absolute doc_dir path', async () => {
       await expect(
         validateMkdocsYaml(inputDir, '/mkdocs_invalid_doc_dir.yml'),

packages/techdocs-common/src/stages/generate/helpers.ts

@@ -19,6 +19,7 @@ import { isChildPath } from '@backstage/backend-common';
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
 import yaml, { DEFAULT_SCHEMA, Type } from 'js-yaml';
+import { resolve as resolvePath } from 'path';
 import { PassThrough, Writable } from 'stream';
 import { Logger } from 'winston';
 import { ParsedLocationAnnotation } from '../../helpers';
@@ -178,7 +179,10 @@ export const validateMkdocsYaml = async (
     schema: MKDOCS_SCHEMA,
   });
 
-  if (mkdocsYml.docs_dir && !isChildPath(inputDir, mkdocsYml.docs_dir)) {
+  if (
+    mkdocsYml.docs_dir &&
+    !isChildPath(inputDir, resolvePath(inputDir, mkdocsYml.docs_dir))
+  ) {
     throw new Error(
       `docs_dir configuration value in mkdocs can't be an absolute directory or start with ../ for security reasons.
        Use relative paths instead which are resolved relative to your mkdocs.yml file location.`,

packages/techdocs-common/src/stages/generate/techdocs.test.ts

@@ -132,7 +132,8 @@ describe('readGeneratorConfig', () => {
         runIn: 'local',
       });
       expect(logger.warn).toHaveBeenCalledWith(
-        `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead.`,
+        `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +
+          `See here https://backstage.io/docs/features/techdocs/configuration`,
       );
     });
   });

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -168,7 +168,8 @@ export function readGeneratorConfig(
 
   if (legacyGeneratorType) {
     logger.warn(
-      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead.`,
+      `The 'techdocs.generators.techdocs' configuration key is deprecated and will be removed in the future. Please use 'techdocs.generator' instead. ` +
+        `See here https://backstage.io/docs/features/techdocs/configuration`,
     );
   }