fix: add docs tag validation to solve #5478 (#5479)

* fix: add docs tag validation to solve #5478

fix: add docs tag validation to solve #5478

* Update docFrontMatter.ts

* Update docs-create-doc.mdx

* improve tag validation error messages + tests

* improve tags doc

* fix test

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

packages/docusaurus-plugin-content-blog/src/__tests__/blogFrontMatter.test.ts

@@ -314,7 +314,7 @@ describe('validateBlogPostFrontMatter tags', () => {
       {tags: ['hello', {label: 'tagLabel', permalink: '/tagPermalink'}]},
     ],
     invalidFrontMatters: [
-      [{tags: ''}, 'must be an array'],
+      [{tags: ''}, '"tags" does not look like a valid FrontMatter Yaml array.'],
       [{tags: ['']}, 'not allowed to be empty'],
     ],
     // See https://github.com/facebook/docusaurus/issues/4642

packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts

@@ -242,3 +242,24 @@ describe('validateDocFrontMatter parse_number_prefixes', () => {
     ],
   });
 });
+
+describe('validateDocFrontMatter tags', () => {
+  testField({
+    fieldName: 'tags',
+    validFrontMatters: [{}, {tags: undefined}, {tags: ['tag1', 'tag2']}],
+    convertibleFrontMatter: [[{tags: ['tag1', 42]}, {tags: ['tag1', '42']}]],
+    invalidFrontMatters: [
+      [{tags: 42}, '"tags" does not look like a valid FrontMatter Yaml array.'],
+      [
+        {tags: 'tag1, tag2'},
+        '"tags" does not look like a valid FrontMatter Yaml array.',
+      ],
+      [{tags: [{}]}, '"tags[0]" does not look like a valid tag'],
+      [{tags: [true]}, '"tags[0]" does not look like a valid tag'],
+      [
+        {tags: ['tag1', {hey: 'test'}]},
+        '"tags[1]" does not look like a valid tag',
+      ],
+    ],
+  });
+});

packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts

@@ -8,6 +8,7 @@
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
+  FrontMatterTagsSchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
 import {DocFrontMatter} from './types';
@@ -27,6 +28,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),

packages/docusaurus-utils-validation/src/validationSchemas.ts

@@ -61,12 +61,22 @@ export const PathnameSchema = Joi.string()
     '{{#label}} is not a valid pathname. Pathname should start with slash and not contain any domain or query string.',
   );
 
-export const FrontMatterTagsSchema = JoiFrontMatter.array().items(
-  JoiFrontMatter.alternatives().try(
+const FrontMatterTagSchema = JoiFrontMatter.alternatives()
+  .try(
     JoiFrontMatter.string().required(),
     JoiFrontMatter.object<Tag>({
       label: JoiFrontMatter.string().required(),
       permalink: JoiFrontMatter.string().required(),
     }).required(),
-  ),
-);
+  )
+  .messages({
+    'alternatives.match': '{{#label}} does not look like a valid tag',
+    'alternatives.types': '{{#label}} does not look like a valid tag',
+  });
+
+export const FrontMatterTagsSchema = JoiFrontMatter.array()
+  .items(FrontMatterTagSchema)
+  .messages({
+    'array.base':
+      '{{#label}} does not look like a valid FrontMatter Yaml array.',
+  });

website/docs/guides/docs/docs-create-doc.mdx

@@ -99,3 +99,11 @@ tags:
 ---
 ```
 <!-- prettier-ignore-end -->
+
+:::tip
+
+Tags can also be declared with `tags [Demo, Getting started]`
+
+Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
+
+:::