feat: doc tags (same as blog tags) (#3646)

* [v2] tags to doc, same as tags to blog - [IN PROGRESS] - Addition of plugin-content-docs - Addition of DocTagsListPage in `docusaurus-theme-classic` ! Error exists for this commit towards the theme aspect and help required. Commit towards #3434 * docs: make tags list page work * temp: disable onBrokenLinks * theme bootstrap: create DocTagsListPage * DocTagsPage added and functionality too - individual doc tag page added to show docs for that specific tag * Added all Docs Tags Link * add some shared tag utils * move tag tests to _dogfooding * fix type * fix some tests * fix blog test * refactor blog post tags handling * better yaml tag examples * better dogfood md files * refactor and factorize theme tag components * finish DocTagDocListPage * Extract DocItemFooter + add inline tag list * minor fix * better typings * fix versions.test.ts tests * add tests for doc tags * fix tests * test toTagDocListProp * move shared theme code to tagUtils * Add new theme translation keys * move common theme code to tagUtils + add tests * update-code-translations should handle theme-common * update french translation * revert add translation * fix pluralization problem in theme.docs.tagDocListPageTitle * add theme component configuration options * add more tags tests * add documentation for docs tagging Co-authored-by: slorber <[email protected]>
facebook · Aug 19, 2021 · f9c79cb · f9c79cb
1 parent f666de7
commit f9c79cb
Show file tree

Hide file tree

Showing 81 changed files with 1,874 additions and 381 deletions.
diff --git a/jest.config.js b/jest.config.js
@@ -33,6 +33,11 @@ module.exports = {
   },
   setupFiles: ['./jest/stylelint-rule-test.js', './jest/polyfills.js'],
   moduleNameMapper: {
+    // TODO we need to allow Jest to resolve core Webpack aliases automatically
     '@docusaurus/router': 'react-router-dom',
+    '@docusaurus/Translate': '@docusaurus/core/lib/client/exports/Translate',
+    '@docusaurus/Interpolate':
+      '@docusaurus/core/lib/client/exports/Interpolate',
+    '@generated/codeTranslations': '<rootDir>/jest/emptyModule.js',
   },
 };
diff --git a/jest/emptyModule.js b/jest/emptyModule.js
@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {};
diff --git a/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts b/packages/docusaurus-plugin-content-blog/src/blogFrontMatter.ts
@@ -9,15 +9,16 @@ import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
   validateFrontMatter,
+  FrontMatterTagsSchema,
 } from '@docusaurus/utils-validation';
-import {Tag} from './types';
+import type {FrontMatterTag} from '@docusaurus/utils';
 
 export type BlogPostFrontMatter = {
   /* eslint-disable camelcase */
   id?: string;
   title?: string;
   description?: string;
-  tags?: (string | Tag)[];
+  tags?: FrontMatterTag[];
   slug?: string;
   draft?: boolean;
   date?: Date | string; // Yaml automagically convert some string patterns as Date, but not all
@@ -38,23 +39,11 @@ export type BlogPostFrontMatter = {
   /* eslint-enable camelcase */
 };
 
-// NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
-// While the user did not provide those values explicitly
-// We use default values in code instead
-const BlogTagSchema = Joi.alternatives().try(
-  Joi.string().required(),
-  Joi.object<Tag>({
-    label: Joi.string().required(),
-    permalink: Joi.string().required(),
-  }),
-);
-
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
   description: Joi.string().allow(''),
-  tags: Joi.array().items(BlogTagSchema),
+  tags: FrontMatterTagsSchema,
   draft: Joi.boolean(),
   date: Joi.date().raw(),
 

diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
@@ -16,6 +16,7 @@ import {
   BlogPost,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
+  BlogTags,
 } from './types';
 import {
   parseMarkdownFile,
@@ -26,6 +27,8 @@ import {
   posixPath,
   replaceMarkdownLinks,
   Globby,
+  normalizeFrontMatterTags,
+  groupTaggedItems,
 } from '@docusaurus/utils';
 import {LoadContext} from '@docusaurus/types';
 import {validateBlogPostFrontMatter} from './blogFrontMatter';
@@ -43,6 +46,20 @@ export function getSourceToPermalink(
   );
 }
 
+export function getBlogTags(blogPosts: BlogPost[]): BlogTags {
+  const groups = groupTaggedItems(
+    blogPosts,
+    (blogPost) => blogPost.metadata.tags,
+  );
+  return mapValues(groups, (group) => {
+    return {
+      name: group.tag.label,
+      items: group.items.map((item) => item.id),
+      permalink: group.tag.permalink,
+    };
+  });
+}
+
 const DATE_FILENAME_REGEX = /^(?<date>\d{4}[-/]\d{1,2}[-/]\d{1,2})[-/]?(?<text>.*?)(\/index)?.mdx?$/;
 
 type ParsedBlogFileName = {
@@ -240,6 +257,8 @@ async function processBlogSourceFile(
     return undefined;
   }
 
+  const tagsBasePath = normalizeUrl([baseUrl, options.routeBasePath, 'tags']); // make this configurable?
+
   return {
     id: frontMatter.slug ?? title,
     metadata: {
@@ -250,7 +269,7 @@ async function processBlogSourceFile(
       description,
       date,
       formattedDate,
-      tags: frontMatter.tags ?? [],
+      tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
       readingTime: showReadingTime ? readingTime(content).minutes : undefined,
       truncated: truncateMarker?.test(content) || false,
     },

diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts
@@ -22,7 +22,7 @@ import {
   STATIC_DIR_NAME,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/core/lib/constants';
-import {flatten, take, kebabCase} from 'lodash';
+import {flatten, take} from 'lodash';
 
 import {
   PluginOptions,
@@ -51,6 +51,7 @@ import {
   generateBlogPosts,
   getContentPathList,
   getSourceToPermalink,
+  getBlogTags,
 } from './blogUtils';
 
 export default function pluginContentBlog(
@@ -65,7 +66,7 @@ export default function pluginContentBlog(
 
   const {
     siteDir,
-    siteConfig: {onBrokenMarkdownLinks},
+    siteConfig: {onBrokenMarkdownLinks, baseUrl},
     generatedFilesDir,
     i18n: {currentLocale},
   } = context;
@@ -151,17 +152,14 @@ export default function pluginContentBlog(
       const postsPerPage =
         postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
       const numberOfPages = Math.ceil(totalCount / postsPerPage);
-      const {
-        siteConfig: {baseUrl = ''},
-      } = context;
-      const basePageUrl = normalizeUrl([baseUrl, routeBasePath]);
+      const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]);
 
       const blogListPaginated: BlogPaginated[] = [];
 
       function blogPaginationPermalink(page: number) {
         return page > 0
-          ? normalizeUrl([basePageUrl, `page/${page + 1}`])
-          : basePageUrl;
+          ? normalizeUrl([baseBlogUrl, `page/${page + 1}`])
+          : baseBlogUrl;
       }
 
       for (let page = 0; page < numberOfPages; page += 1) {
@@ -186,41 +184,9 @@ export default function pluginContentBlog(
         });
       }
 
-      const blogTags: BlogTags = {};
-      const tagsPath = normalizeUrl([basePageUrl, 'tags']);
-      blogPosts.forEach((blogPost) => {
-        const {tags} = blogPost.metadata;
-        if (!tags || tags.length === 0) {
-          // TODO: Extract tags out into a separate plugin.
-          // eslint-disable-next-line no-param-reassign
-          blogPost.metadata.tags = [];
-          return;
-        }
+      const blogTags: BlogTags = getBlogTags(blogPosts);
 
-        // eslint-disable-next-line no-param-reassign
-        blogPost.metadata.tags = tags.map((tag) => {
-          if (typeof tag === 'string') {
-            const normalizedTag = kebabCase(tag);
-            const permalink = normalizeUrl([tagsPath, normalizedTag]);
-            if (!blogTags[normalizedTag]) {
-              blogTags[normalizedTag] = {
-                // Will only use the name of the first occurrence of the tag.
-                name: tag.toLowerCase(),
-                items: [],
-                permalink,
-              };
-            }
-
-            blogTags[normalizedTag].items.push(blogPost.id);
-
-            return {
-              label: tag,
-              permalink,
-            };
-          }
-          return tag;
-        });
-      });
+      const tagsPath = normalizeUrl([baseBlogUrl, 'tags']);
 
       const blogTagsListPath =
         Object.keys(blogTags).length > 0 ? tagsPath : null;
@@ -348,6 +314,7 @@ export default function pluginContentBlog(
         Object.keys(blogTags).map(async (tag) => {
           const {name, items, permalink} = blogTags[tag];
 
+          // Refactor all this, see docs implementation
           tagsModule[tag] = {
             allTagsPath: blogTagsListPath,
             slug: tag,
@@ -535,7 +502,6 @@ export default function pluginContentBlog(
       const feedTypes = options.feedOptions.type;
       const {
         siteConfig: {title},
-        baseUrl,
       } = context;
       const feedsConfig = {
         rss: {

diff --git a/packages/docusaurus-plugin-content-blog/src/types.ts b/packages/docusaurus-plugin-content-blog/src/types.ts
@@ -6,7 +6,8 @@
  */
 
 import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import {
+import type {Tag} from '@docusaurus/utils';
+import type {
   BrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
@@ -96,7 +97,7 @@ export interface MetaData {
   description: string;
   date: Date;
   formattedDate: string;
-  tags: (Tag | string)[];
+  tags: Tag[];
   title: string;
   readingTime?: number;
   prevItem?: Paginator;
@@ -110,11 +111,6 @@ export interface Paginator {
   permalink: string;
 }
 
-export interface Tag {
-  label: string;
-  permalink: string;
-}
-
 export interface BlogItemsToMetadata {
   [key: string]: MetaData;
 }

diff --git a/...urus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md b/...urus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/foo/baz.md
@@ -3,6 +3,11 @@ id: baz
 title: baz
 slug: bazSlug.html
 pagination_label: baz pagination_label
+tags:
+  - tag 1
+  - tag-1
+  - label: tag 2
+    permalink: tag2-custom-permalink
 ---
 
 # Baz markdown title

diff --git a/...saurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md b/...saurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md
@@ -2,6 +2,7 @@
 id: hello
 title: Hello, World !
 sidebar_label: Hello sidebar_label
+tags: [tag-1, tag 3]
 ---
 
 Hi, Endilie here :)

diff --git a/...s-plugin-content-docs/src/__tests__/__fixtures__/versioned-site/docs/foo/bar.md b/...s-plugin-content-docs/src/__tests__/__fixtures__/versioned-site/docs/foo/bar.md
@@ -1,4 +1,10 @@
 ---
 slug: barSlug
+tags:
+  - barTag 1
+  - barTag-2
+  - label: barTag 3
+    permalink: barTag-3-permalink
 ---
+
 This is `next` version of bar.