Merge pull request #23050 from jackmtpt/fix-techdocs-default-plugins-with-config

Fix techdocs default plugins with config

plugins/techdocs-node/src/stages/generate/__fixtures__/mkdocs_with_additional_plugins_with_config.yml

@@ -0,0 +1,9 @@
+site_name: Test site name
+site_description: Test site description
+docs_dir: docs/
+plugins:
+  - not-techdocs-core
+  - also-not-techdocs-core
+  - custom-plugin:
+      with:
+        configuration: 1

plugins/techdocs-node/src/stages/generate/helpers.test.ts

@@ -81,6 +81,12 @@ const mkdocsYmlWithoutPlugins = fs.readFileSync(
 const mkdocsYmlWithAdditionalPlugins = fs.readFileSync(
   resolvePath(__filename, '../__fixtures__/mkdocs_with_additional_plugins.yml'),
 );
+const mkdocsYmlWithAdditionalPluginsWithConfig = fs.readFileSync(
+  resolvePath(
+    __filename,
+    '../__fixtures__/mkdocs_with_additional_plugins_with_config.yml',
+  ),
+);
 const mkdocsYmlWithEnvTag = fs.readFileSync(
   resolvePath(__filename, '../__fixtures__/mkdocs_with_env_tag.yml'),
 );
@@ -321,6 +327,8 @@ describe('helpers', () => {
         'mkdocs_with_techdocs_plugin.yml': mkdocsYmlWithTechdocsPlugins,
         'mkdocs_without_plugins.yml': mkdocsYmlWithoutPlugins,
         'mkdocs_with_additional_plugins.yml': mkdocsYmlWithAdditionalPlugins,
+        'mkdocs_with_additional_plugins_with_config.yml':
+          mkdocsYmlWithAdditionalPluginsWithConfig,
       });
     });
     it('should not add additional plugins if techdocs exists already in mkdocs file', async () => {
@@ -386,6 +394,28 @@ describe('helpers', () => {
       expect(parsedYml.plugins).toContain('techdocs-core');
       expect(parsedYml.plugins).toContain('custom-plugin');
     });
+    it('should not overwrite config when defaults are added', async () => {
+      await patchMkdocsYmlWithPlugins(
+        mockDir.resolve('mkdocs_with_additional_plugins_with_config.yml'),
+        mockLogger,
+        ['techdocs-core', 'custom-plugin'],
+      );
+
+      const updatedMkdocsYml = await fs.readFile(
+        mockDir.resolve('mkdocs_with_additional_plugins_with_config.yml'),
+      );
+      const parsedYml = yaml.load(updatedMkdocsYml.toString()) as {
+        plugins: object[];
+      };
+      expect(parsedYml.plugins).toHaveLength(4);
+      expect(parsedYml.plugins).toContain('techdocs-core');
+      // we want our original object with its properties to be preserved, and for the basic string form of the plugin
+      // to NOT be added as well.
+      expect(parsedYml.plugins).not.toContain('custom-plugin');
+      expect(parsedYml.plugins).toContainEqual({
+        'custom-plugin': { with: { configuration: 1 } },
+      });
+    });
   });
 
   describe('patchIndexPreBuild', () => {

plugins/techdocs-node/src/stages/generate/mkdocsPatchers.ts

@@ -153,21 +153,30 @@ export const patchMkdocsYmlWithPlugins = async (
   defaultPlugins: string[] = ['techdocs-core'],
 ) => {
   await patchMkdocsFile(mkdocsYmlPath, logger, mkdocsYml => {
-    // Modify mkdocs.yaml to contain the required default plugins
+    // Modify mkdocs.yaml to contain the required default plugins.
+    // If no plugins are defined we can just return the defaults.
     if (!('plugins' in mkdocsYml)) {
       mkdocsYml.plugins = defaultPlugins;
       return true;
     }
 
-    if (
-      mkdocsYml.plugins &&
-      !defaultPlugins.every(plugin => mkdocsYml.plugins!.includes(plugin))
-    ) {
-      mkdocsYml.plugins = [
-        ...new Set([...mkdocsYml.plugins, ...defaultPlugins]),
-      ];
-      return true;
-    }
-    return false;
+    // Otherwise, check each default plugin and include it if necessary.
+    let changesMade = false;
+
+    defaultPlugins.forEach(dp => {
+      // if the plugin isn't there as a string, and isn't there as an object (which may itself contain extra config)
+      // then we need to add it
+      if (
+        !(
+          mkdocsYml.plugins!.includes(dp) ||
+          mkdocsYml.plugins!.some(p => p.hasOwnProperty(dp))
+        )
+      ) {
+        mkdocsYml.plugins = [...new Set([...mkdocsYml.plugins!, dp])];
+        changesMade = true;
+      }
+    });
+
+    return changesMade;
   });
 };