feat(docs, blog): add support for tags.yml, predefined list of tags

packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/index.test.ts.snap

@@ -148,6 +148,8 @@ exports[`blog plugin process blog posts load content 2`] = `
       "source": "@site/blog/another-simple-slug-with-tags.md",
       "tags": [
         {
+          "description": undefined,
+          "inline": true,
           "label": "tag1",
           "permalink": "/blog/tags/tag-1",
         },
@@ -189,10 +191,14 @@ exports[`blog plugin process blog posts load content 2`] = `
       "source": "@site/blog/another-with-tags.md",
       "tags": [
         {
+          "description": undefined,
+          "inline": true,
           "label": "tag1",
           "permalink": "/blog/tags/tag-1",
         },
         {
+          "description": undefined,
+          "inline": true,
           "label": "tag2",
           "permalink": "/blog/tags/tag-2",
         },
@@ -230,10 +236,14 @@ exports[`blog plugin process blog posts load content 2`] = `
       "source": "@site/blog/another-with-tags2.md",
       "tags": [
         {
+          "description": undefined,
+          "inline": true,
           "label": "tag1",
           "permalink": "/blog/tags/tag-1",
         },
         {
+          "description": undefined,
+          "inline": true,
           "label": "tag2",
           "permalink": "/blog/tags/tag-2",
         },

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

@@ -100,6 +100,8 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
         readingTime: ({content, defaultReadingTime}) =>
           defaultReadingTime({content}),
         truncateMarker: /<!--\s*truncate\s*-->/,
+        onInlineTags: 'ignore',
+        tags: false,
       } as PluginOptions,
     );
 
@@ -141,6 +143,8 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
         readingTime: ({content, defaultReadingTime}) =>
           defaultReadingTime({content}),
         truncateMarker: /<!--\s*truncate\s*-->/,
+        onInlineTags: 'ignore',
+        tags: false,
       } as PluginOptions,
     );
 
@@ -194,6 +198,8 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
         readingTime: ({content, defaultReadingTime}) =>
           defaultReadingTime({content}),
         truncateMarker: /<!--\s*truncate\s*-->/,
+        onInlineTags: 'ignore',
+        tags: false,
       } as PluginOptions,
     );
 
@@ -238,6 +244,8 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
         readingTime: ({content, defaultReadingTime}) =>
           defaultReadingTime({content}),
         truncateMarker: /<!--\s*truncate\s*-->/,
+        onInlineTags: 'ignore',
+        tags: false,
       } as PluginOptions,
     );
 
@@ -282,6 +290,8 @@ describe.each(['atom', 'rss', 'json'])('%s', (feedType) => {
         readingTime: ({content, defaultReadingTime}) =>
           defaultReadingTime({content}),
         truncateMarker: /<!--\s*truncate\s*-->/,
+        onInlineTags: 'ignore',
+        tags: false,
       } as PluginOptions,
     );
 

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

@@ -188,6 +188,8 @@ describe('blog plugin', () => {
       prevItem: undefined,
       tags: [
         {
+          description: undefined,
+          inline: true,
           label: 'date',
           permalink: '/blog/tags/date',
         },
@@ -269,10 +271,14 @@ describe('blog plugin', () => {
       },
       tags: [
         {
+          description: undefined,
+          inline: true,
           label: 'date',
           permalink: '/blog/tags/date',
         },
         {
+          description: undefined,
+          inline: true,
           label: 'complex',
           permalink: '/blog/tags/complex',
         },
@@ -516,6 +522,8 @@ describe('blog plugin', () => {
         postsPerPage: 1,
         processBlogPosts: async ({blogPosts}) =>
           blogPosts.filter((blog) => blog.metadata.tags[0]?.label === 'tag1'),
+        onInlineTags: 'ignore',
+        tags: false,
       },
       DefaultI18N,
     );

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -18,17 +18,19 @@ import {
   getFolderContainingFile,
   posixPath,
   Globby,
-  normalizeFrontMatterTags,
   groupTaggedItems,
   getTagVisibility,
   getFileCommitDate,
   getContentPathList,
   isUnlisted,
   isDraft,
   readLastUpdateData,
+  processFileTagsPath,
 } from '@docusaurus/utils';
+import {getTagsFile} from '@docusaurus/utils-validation';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import type {TagsFile} from '@docusaurus/utils';
 import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
   PluginOptions,
@@ -197,6 +199,7 @@ async function processBlogSourceFile(
   contentPaths: BlogContentPaths,
   context: LoadContext,
   options: PluginOptions,
+  tagsFile: TagsFile | null,
   authorsMap?: AuthorsMap,
 ): Promise<BlogPost | undefined> {
   const {
@@ -322,6 +325,14 @@ async function processBlogSourceFile(
   ]);
   const authors = getBlogPostAuthors({authorsMap, frontMatter, baseUrl});
 
+  const tags = processFileTagsPath({
+    options,
+    source: blogSourceRelative,
+    frontMatterTags: frontMatter.tags,
+    versionTagsPath: tagsBasePath,
+    tagsFile,
+  });
+
   return {
     id: slug,
     metadata: {
@@ -331,7 +342,7 @@ async function processBlogSourceFile(
       title,
       description,
       date,
-      tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
+      tags,
       readingTime: showReadingTime
         ? options.readingTime({
             content,
@@ -371,13 +382,16 @@ export async function generateBlogPosts(
     authorsMapPath: options.authorsMapPath,
   });
 
+  const tagsFile = await getTagsFile(options, contentPaths.contentPath);
+
   async function doProcessBlogSourceFile(blogSourceFile: string) {
     try {
       return await processBlogSourceFile(
         blogSourceFile,
         contentPaths,
         context,
         options,
+        tagsFile,
         authorsMap,
       );
     } catch (err) {

packages/docusaurus-plugin-content-blog/src/frontMatter.ts

@@ -9,10 +9,11 @@ import {
   FrontMatterLastUpdateSchema,
   FrontMatterTOCHeadingLevels,
   FrontMatterTagsSchema,
-  JoiFrontMatter as Joi, // Custom instance for front matter
+  Joi, // Custom instance for front matter
   URISchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
+import type {TagsFile} from '@docusaurus/utils';
 import type {BlogPostFrontMatter} from '@docusaurus/plugin-content-blog';
 
 const BlogPostFrontMatterAuthorSchema = Joi.object({
@@ -82,3 +83,18 @@ export function validateBlogPostFrontMatter(frontMatter: {
 }): BlogPostFrontMatter {
   return validateFrontMatter(frontMatter, BlogFrontMatterSchema);
 }
+
+export const tagDefinitionSchema = Joi.object<TagsFile>().pattern(
+  Joi.string(),
+  Joi.object({
+    label: Joi.string().required(),
+    description: Joi.string().required(),
+    permalink: Joi.string(),
+  }),
+);
+
+export function validateDefinedTags(
+  tags: unknown,
+): Joi.ValidationResult<TagsFile> {
+  return tagDefinitionSchema.validate(tags);
+}

packages/docusaurus-plugin-content-blog/src/options.ts

@@ -54,6 +54,8 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
   processBlogPosts: async () => undefined,
+  onInlineTags: 'warn',
+  tags: undefined,
 };
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -144,6 +146,13 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   processBlogPosts: Joi.function()
     .optional()
     .default(() => DEFAULT_OPTIONS.processBlogPosts),
+  onInlineTags: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onInlineTags),
+  tags: Joi.string()
+    .disallow('')
+    .allow(null, false)
+    .default(() => DEFAULT_OPTIONS.tags),
 }).default(DEFAULT_OPTIONS);
 
 export function validateOptions({