feat(v2): allow to use array of files in customCss field (#3474)

* feat(v2): allow to use array of files in customCss field

* customCss array:
- fix bug (push instead of concat)
- update docs
- add theme config validation + tests

Co-authored-by: slorber <lorber.sebastien@gmail.com>

packages/docusaurus-theme-classic/src/__tests__/validateThemeConfig.test.js

@@ -15,6 +15,13 @@ function testValidateThemeConfig(themeConfig) {
   return normalizeThemeConfig(ThemeConfigSchema, themeConfig);
 }
 
+function testOk(partialConfig) {
+  expect(testValidateThemeConfig(partialConfig)).toEqual({
+    ...DEFAULT_CONFIG,
+    ...partialConfig,
+  });
+}
+
 describe('themeConfig', () => {
   test('should accept valid theme config', () => {
     const userConfig = {
@@ -110,6 +117,36 @@ describe('themeConfig', () => {
     });
   });
 
+  describe.only('customCss config', () => {
+    test('should accept customCss undefined', () => {
+      testOk({
+        customCss: undefined,
+      });
+    });
+
+    test('should accept customCss string', () => {
+      testOk({
+        customCss: './path/to/cssFile.css',
+      });
+    });
+
+    test('should accept customCss string array', () => {
+      testOk({
+        customCss: ['./path/to/cssFile.css', './path/to/cssFile2.css'],
+      });
+    });
+
+    test('should reject customCss number', () => {
+      expect(() =>
+        testValidateThemeConfig({
+          customCss: 42,
+        }),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"\\"customCss\\" must be one of [array, string]"`,
+      );
+    });
+  });
+
   describe('color mode config', () => {
     const withDefaultValues = (colorMode) =>
       merge({}, DEFAULT_CONFIG.colorMode, colorMode);

packages/docusaurus-theme-classic/src/index.js

@@ -83,7 +83,11 @@ module.exports = function (context, options) {
       ];
 
       if (customCss) {
-        modules.push(customCss);
+        if (Array.isArray(customCss)) {
+          modules.push(...customCss);
+        } else {
+          modules.push(customCss);
+        }
       }
 
       return modules;

packages/docusaurus-theme-classic/src/validateThemeConfig.js

@@ -165,6 +165,10 @@ const FooterLinkItemSchema = Joi.object({
   // (users may need additional attributes like target, aria-role, data-customAttribute...)
   .unknown();
 
+const CustomCssSchema = Joi.alternatives()
+  .try(Joi.array().items(Joi.string().required()), Joi.string().required())
+  .optional();
+
 const ThemeConfigSchema = Joi.object({
   // TODO temporary (@alpha-58)
   disableDarkMode: Joi.any().forbidden(false).messages({
@@ -176,6 +180,7 @@ const ThemeConfigSchema = Joi.object({
     'any.unknown':
       'defaultDarkMode theme config is deprecated. Please use the new colorMode attribute. You likely want: config.themeConfig.colorMode.defaultMode = "dark"',
   }),
+  customCss: CustomCssSchema,
   colorMode: ColorModeSchema,
   image: Joi.string(),
   metadatas: Joi.array()

website/docs/configuration.md

@@ -95,7 +95,7 @@ module.exports = {
           sidebarPath: require.resolve('./sidebars.js'),
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: [require.resolve('./src/css/custom.css')],
         },
       },
     ],

website/docs/guides/migrating-from-v1-to-v2.md

@@ -220,7 +220,7 @@ module.exports = {
       '@docusaurus/preset-classic',
       {
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: [require.resolve('./src/css/custom.css')],
         },
       },
     ],

website/docs/presets.md

@@ -97,7 +97,7 @@ module.exports = {
         debug: undefined,
         // Will be passed to @docusaurus/theme-classic.
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: [require.resolve('./src/css/custom.css')],
         },
         // Will be passed to @docusaurus/plugin-content-docs (false to disable)
         docs: {},

website/docs/styling-layout.md

@@ -19,7 +19,7 @@ module.exports = {
       {
         // highlight-start
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: [require.resolve('./src/css/custom.css')],
         },
         // highlight-end
       },
@@ -164,7 +164,7 @@ module.exports = {
       {
         // ...
         theme: {
-          customCss: require.resolve('./src/css/custom.scss'),
+          customCss: [require.resolve('./src/css/custom.scss')],
         },
         // ...
       },

website/docusaurus.config.js

@@ -207,7 +207,7 @@ module.exports = {
           remarkPlugins: [require('./src/plugins/remark-npm2yarn')],
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: [require.resolve('./src/css/custom.css')],
         },
       },
     ],