Only write the updated mkdocs.yml file if the content was updated

Signed-off-by: Dominik Henneke <dominik.henneke@sda-se.com>

.changeset/techdocs-three-icons-collect.md

@@ -0,0 +1,7 @@
+---
+'@backstage/techdocs-common': patch
+---
+
+Only write the updated `mkdocs.yml` file if the content was updated.
+
+This keeps local files unchanged if the `dir` annotation is used in combination with the `file` location.

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

@@ -0,0 +1,3 @@
+site_name: Test site name
+site_description: Test site description
+# This is a comment that is removed after editing

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

@@ -61,6 +61,9 @@ const mkdocsYmlWithInvalidDocDir = fs.readFileSync(
 const mkdocsYmlWithInvalidDocDir2 = fs.readFileSync(
   resolvePath(__filename, '../__fixtures__/mkdocs_invalid_doc_dir2.yml'),
 );
+const mkdocsYmlWithComments = fs.readFileSync(
+  resolvePath(__filename, '../__fixtures__/mkdocs_with_comments.yml'),
+);
 const mockLogger = getVoidLogger();
 const rootDir = os.platform() === 'win32' ? 'C:\\rootDir' : '/rootDir';
 
@@ -163,6 +166,7 @@ describe('helpers', () => {
         '/mkdocs_with_repo_url.yml': mkdocsYmlWithRepoUrl,
         '/mkdocs_with_edit_uri.yml': mkdocsYmlWithEditUri,
         '/mkdocs_with_extensions.yml': mkdocsYmlWithExtensions,
+        '/mkdocs_with_comments.yml': mkdocsYmlWithComments,
       });
     });
 
@@ -258,6 +262,28 @@ describe('helpers', () => {
         'https://github.com/neworg/newrepo',
       );
     });
+
+    it('should not update mkdocs.yml if nothing should be changed', async () => {
+      const parsedLocationAnnotation: ParsedLocationAnnotation = {
+        type: 'dir',
+        target: '/unsupported/path',
+      };
+
+      await patchMkdocsYmlPreBuild(
+        '/mkdocs_with_comments.yml',
+        mockLogger,
+        parsedLocationAnnotation,
+        scmIntegrations,
+      );
+
+      const updatedMkdocsYml = await fs.readFile('/mkdocs_with_comments.yml');
+
+      expect(updatedMkdocsYml.toString()).toContain(
+        '# This is a comment that is removed after editing',
+      );
+      expect(updatedMkdocsYml.toString()).not.toContain('edit_uri');
+      expect(updatedMkdocsYml.toString()).not.toContain('repo_url');
+    });
   });
 
   describe('addBuildTimestampMetadata', () => {

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

@@ -217,6 +217,10 @@ export const patchMkdocsYmlPreBuild = async (
   parsedLocationAnnotation: ParsedLocationAnnotation,
   scmIntegrations: ScmIntegrationRegistry,
 ) => {
+  // We only want to override the mkdocs.yml if it has actually changed. This is relevant if
+  // used with a 'dir' location on the file system as this would permanently update the file.
+  let didEdit = false;
+
   let mkdocsYmlFileString;
   try {
     mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');
@@ -256,6 +260,7 @@ export const patchMkdocsYmlPreBuild = async (
     if (result.repo_url || result.edit_uri) {
       mkdocsYml.repo_url = result.repo_url;
       mkdocsYml.edit_uri = result.edit_uri;
+      didEdit = true;
 
       logger.info(
         `Set ${JSON.stringify(
@@ -266,11 +271,13 @@ export const patchMkdocsYmlPreBuild = async (
   }
 
   try {
-    await fs.writeFile(
-      mkdocsYmlPath,
-      yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),
-      'utf8',
-    );
+    if (didEdit) {
+      await fs.writeFile(
+        mkdocsYmlPath,
+        yaml.dump(mkdocsYml, { schema: MKDOCS_SCHEMA }),
+        'utf8',
+      );
+    }
   } catch (error) {
     logger.warn(
       `Could not write to ${mkdocsYmlPath} after updating it before running the generator. ${error.message}`,