refactor(content-blog): clean up type definitions; in-code documentat…

…ion (#6922) * refactor(content-blog): clean up type definitions; in-code documentation * add doc
facebook · Mar 16, 2022 · 8d1c195 · 8d1c195
1 parent 46b1027
commit 8d1c195
Show file tree

Hide file tree

Showing 16 changed files with 447 additions and 178 deletions.
diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap
@@ -37,7 +37,7 @@ exports[`paginateBlogPosts generates right pages 1`] = `
       "page": 1,
       "permalink": "/blog",
       "postsPerPage": 2,
-      "previousPage": null,
+      "previousPage": undefined,
       "totalCount": 5,
       "totalPages": 3,
     },
@@ -66,7 +66,7 @@ exports[`paginateBlogPosts generates right pages 1`] = `
     "metadata": {
       "blogDescription": "Blog Description",
       "blogTitle": "Blog Title",
-      "nextPage": null,
+      "nextPage": undefined,
       "page": 3,
       "permalink": "/blog/page/3",
       "postsPerPage": 2,
@@ -92,7 +92,7 @@ exports[`paginateBlogPosts generates right pages 2`] = `
       "page": 1,
       "permalink": "/",
       "postsPerPage": 2,
-      "previousPage": null,
+      "previousPage": undefined,
       "totalCount": 5,
       "totalPages": 3,
     },
@@ -121,7 +121,7 @@ exports[`paginateBlogPosts generates right pages 2`] = `
     "metadata": {
       "blogDescription": "Blog Description",
       "blogTitle": "Blog Title",
-      "nextPage": null,
+      "nextPage": undefined,
       "page": 3,
       "permalink": "/page/3",
       "postsPerPage": 2,
@@ -146,11 +146,11 @@ exports[`paginateBlogPosts generates right pages 3`] = `
     "metadata": {
       "blogDescription": "Blog Description",
       "blogTitle": "Blog Title",
-      "nextPage": null,
+      "nextPage": undefined,
       "page": 1,
       "permalink": "/",
       "postsPerPage": 10,
-      "previousPage": null,
+      "previousPage": undefined,
       "totalCount": 5,
       "totalPages": 1,
     },

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/feed.test.ts.snap
@@ -182,6 +182,7 @@ exports[`rss has feed item for each post 1`] = `
         <lastBuildDate>Sat, 06 Mar 2021 00:00:00 GMT</lastBuildDate>
         <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
         <generator>https://github.com/jpmonette/feed</generator>
+        <language>en</language>
         <copyright>Copyright</copyright>
         <item>
             <title><![CDATA[MDX Blog Sample with require calls]]></title>

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/index.test.ts.snap
@@ -19,11 +19,11 @@ exports[`blog plugin works on blog tags without pagination 1`] = `
         "metadata": {
           "blogDescription": "Blog",
           "blogTitle": "Blog",
-          "nextPage": null,
+          "nextPage": undefined,
           "page": 1,
           "permalink": "/blog/tags/tag-1",
           "postsPerPage": 3,
-          "previousPage": null,
+          "previousPage": undefined,
           "totalCount": 3,
           "totalPages": 1,
         },
@@ -46,11 +46,11 @@ exports[`blog plugin works on blog tags without pagination 1`] = `
         "metadata": {
           "blogDescription": "Blog",
           "blogTitle": "Blog",
-          "nextPage": null,
+          "nextPage": undefined,
           "page": 1,
           "permalink": "/blog/tags/tag-2",
           "postsPerPage": 2,
-          "previousPage": null,
+          "previousPage": undefined,
           "totalCount": 2,
           "totalPages": 1,
         },
@@ -83,7 +83,7 @@ exports[`blog plugin works with blog tags 1`] = `
           "page": 1,
           "permalink": "/blog/tags/tag-1",
           "postsPerPage": 2,
-          "previousPage": null,
+          "previousPage": undefined,
           "totalCount": 3,
           "totalPages": 2,
         },
@@ -95,7 +95,7 @@ exports[`blog plugin works with blog tags 1`] = `
         "metadata": {
           "blogDescription": "Blog",
           "blogTitle": "Blog",
-          "nextPage": null,
+          "nextPage": undefined,
           "page": 2,
           "permalink": "/blog/tags/tag-1/page/2",
           "postsPerPage": 2,
@@ -122,11 +122,11 @@ exports[`blog plugin works with blog tags 1`] = `
         "metadata": {
           "blogDescription": "Blog",
           "blogTitle": "Blog",
-          "nextPage": null,
+          "nextPage": undefined,
           "page": 1,
           "permalink": "/blog/tags/tag-2",
           "postsPerPage": 2,
-          "previousPage": null,
+          "previousPage": undefined,
           "totalCount": 2,
           "totalPages": 1,
         },

diff --git a/...ages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/translations.test.ts.snap b/...ages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/translations.test.ts.snap
@@ -32,11 +32,11 @@ exports[`translateContent falls back when translation is incomplete 1`] = `
       "metadata": {
         "blogDescription": "Someone's random blog",
         "blogTitle": "My blog",
-        "nextPage": null,
+        "nextPage": undefined,
         "page": 1,
         "permalink": "/",
         "postsPerPage": 10,
-        "previousPage": null,
+        "previousPage": undefined,
         "totalCount": 1,
         "totalPages": 1,
       },
@@ -73,11 +73,11 @@ exports[`translateContent returns translated loaded 1`] = `
       "metadata": {
         "blogDescription": "Someone's random blog (translated)",
         "blogTitle": "My blog (translated)",
-        "nextPage": null,
+        "nextPage": undefined,
         "page": 1,
         "permalink": "/",
         "postsPerPage": 10,
-        "previousPage": null,
+        "previousPage": undefined,
         "totalCount": 1,
         "totalPages": 1,
       },

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/feed.test.ts
@@ -49,6 +49,7 @@ async function testGenerateFeeds(
     options,
     siteConfig: context.siteConfig,
     outDir: context.outDir,
+    locale: 'en',
   });
 }
 

diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/translations.test.ts
@@ -45,8 +45,8 @@ const sampleBlogContent: BlogContent = {
         postsPerPage: 10,
         totalPages: 1,
         totalCount: 1,
-        previousPage: null,
-        nextPage: null,
+        previousPage: undefined,
+        nextPage: undefined,
         blogTitle: sampleBlogOptions.blogTitle,
         blogDescription: sampleBlogOptions.blogDescription,
       },

diff --git a/packages/docusaurus-plugin-content-blog/src/authors.ts b/packages/docusaurus-plugin-content-blog/src/authors.ts
@@ -70,7 +70,7 @@ type AuthorsParam = {
 // We may want to deprecate those in favor of using only frontMatter.authors
 function getFrontMatterAuthorLegacy(
   frontMatter: BlogPostFrontMatter,
-): BlogPostFrontMatterAuthor | undefined {
+): Author | undefined {
   const name = frontMatter.author;
   const title = frontMatter.author_title ?? frontMatter.authorTitle;
   const url = frontMatter.author_url ?? frontMatter.authorURL;
@@ -92,7 +92,7 @@ function normalizeFrontMatterAuthors(
   frontMatterAuthors: BlogPostFrontMatterAuthors = [],
 ): BlogPostFrontMatterAuthor[] {
   function normalizeAuthor(
-    authorInput: string | BlogPostFrontMatterAuthor,
+    authorInput: string | Author,
   ): BlogPostFrontMatterAuthor {
     if (typeof authorInput === 'string') {
       // Technically, we could allow users to provide an author's name here, but

diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts
@@ -88,8 +88,8 @@ export function paginateBlogPosts({
         postsPerPage,
         totalPages: numberOfPages,
         totalCount,
-        previousPage: page !== 0 ? permalink(page - 1) : null,
-        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : null,
+        previousPage: page !== 0 ? permalink(page - 1) : undefined,
+        nextPage: page < numberOfPages - 1 ? permalink(page + 1) : undefined,
         blogDescription,
         blogTitle,
       },

diff --git a/packages/docusaurus-plugin-content-blog/src/feed.ts b/packages/docusaurus-plugin-content-blog/src/feed.ts
@@ -29,11 +29,13 @@ async function generateBlogFeed({
   options,
   siteConfig,
   outDir,
+  locale,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
   outDir: string;
+  locale: string;
 }): Promise<Feed | null> {
   if (!blogPosts.length) {
     return null;
@@ -47,11 +49,11 @@ async function generateBlogFeed({
 
   const feed = new Feed({
     id: blogBaseUrl,
-    title: feedOptions.title || `${title} Blog`,
+    title: feedOptions.title ?? `${title} Blog`,
     updated,
-    language: feedOptions.language,
+    language: feedOptions.language ?? locale,
     link: blogBaseUrl,
-    description: feedOptions.description || `${siteConfig.title} Blog`,
+    description: feedOptions.description ?? `${siteConfig.title} Blog`,
     favicon: favicon ? normalizeUrl([siteUrl, baseUrl, favicon]) : undefined,
     copyright: feedOptions.copyright,
   });
@@ -140,17 +142,20 @@ export async function createBlogFeedFiles({
   options,
   siteConfig,
   outDir,
+  locale,
 }: {
   blogPosts: BlogPost[];
   options: PluginOptions;
   siteConfig: DocusaurusConfig;
   outDir: string;
+  locale: string;
 }): Promise<void> {
   const feed = await generateBlogFeed({
     blogPosts,
     options,
     siteConfig,
     outDir,
+    locale,
   });
 
   const feedTypes = options.feedOptions.type;

diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts
@@ -26,13 +26,9 @@ import type {
   BlogTag,
   BlogTags,
   BlogContent,
-  BlogItemsToMetadata,
-  TagsModule,
   BlogPaginated,
   BlogContentPaths,
   BlogMarkdownLoaderOptions,
-  MetaData,
-  TagModule,
 } from './types';
 import {PluginOptionSchema} from './pluginOptionSchema';
 import type {
@@ -52,7 +48,9 @@ import {createBlogFeedFiles} from './feed';
 import type {
   PluginOptions,
   BlogPostFrontMatter,
+  BlogPostMetadata,
   Assets,
+  TagModule,
 } from '@docusaurus/plugin-content-blog';
 
 export default async function pluginContentBlog(
@@ -214,7 +212,7 @@ export default async function pluginContentBlog(
         blogTagsListPath,
       } = blogContents;
 
-      const blogItemsToMetadata: BlogItemsToMetadata = {};
+      const blogItemsToMetadata: Record<string, BlogPostMetadata> = {};
 
       const sidebarBlogPosts =
         options.blogSidebarCount === 'ALL'
@@ -325,11 +323,10 @@ export default async function pluginContentBlog(
         return;
       }
 
-      const tagsModule: TagsModule = Object.fromEntries(
-        Object.entries(blogTags).map(([tagKey, tag]) => {
+      const tagsModule: Record<string, TagModule> = Object.fromEntries(
+        Object.entries(blogTags).map(([, tag]) => {
           const tagModule: TagModule = {
             allTagsPath: blogTagsListPath,
-            slug: tagKey,
             name: tag.name,
             count: tag.items.length,
             permalink: tag.permalink,
@@ -479,7 +476,7 @@ export default async function pluginContentBlog(
                       metadata,
                     }: {
                       frontMatter: BlogPostFrontMatter;
-                      metadata: MetaData;
+                      metadata: BlogPostMetadata;
                     }): Assets => ({
                       image: frontMatter.image,
                       authorsImageUrls: metadata.authors.map(
@@ -512,6 +509,7 @@ export default async function pluginContentBlog(
         options,
         outDir,
         siteConfig,
+        locale: currentLocale,
       });
     },