@docusaurus/plugin-content-blog 0.0.0-5961 → 0.0.0-5963

package/lib/blogUtils.d.ts

@@ -9,9 +9,6 @@ import type { LoadContext } from '@docusaurus/types';
 import type { PluginOptions, BlogPost, BlogTags, BlogPaginated } from '@docusaurus/plugin-content-blog';
 import type { BlogContentPaths } from './types';
 export declare function truncate(fileString: string, truncateMarker: RegExp): string;
-export declare function getSourceToPermalink(blogPosts: BlogPost[]): {
-    [aliasedPath: string]: string;
-};
 export declare function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, pageBasePath, }: {
     blogPosts: BlogPost[];
     basePageUrl: string;

package/lib/blogUtils.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyProcessBlogPosts = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.shouldBeListed = exports.paginateBlogPosts = exports.getSourceToPermalink = exports.truncate = void 0;
+exports.applyProcessBlogPosts = exports.generateBlogPosts = exports.parseBlogFileName = exports.getBlogTags = exports.shouldBeListed = exports.paginateBlogPosts = exports.truncate = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -14,16 +14,13 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const reading_time_1 = tslib_1.__importDefault(require("reading-time"));
 const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
 const frontMatter_1 = require("./frontMatter");
 const authors_1 = require("./authors");
 function truncate(fileString, truncateMarker) {
     return fileString.split(truncateMarker, 1).shift();
 }
 exports.truncate = truncate;
-function getSourceToPermalink(blogPosts) {
-    return Object.fromEntries(blogPosts.map(({ metadata: { source, permalink } }) => [source, permalink]));
-}
-exports.getSourceToPermalink = getSourceToPermalink;
 function paginateBlogPosts({ blogPosts, basePageUrl, blogTitle, blogDescription, postsPerPageOption, pageBasePath, }) {
     const totalCount = blogPosts.length;
     const postsPerPage = postsPerPageOption === 'ALL' ? totalCount : postsPerPageOption;
@@ -67,9 +64,11 @@ function getBlogTags({ blogPosts, ...params }) {
             isUnlisted: (item) => item.metadata.unlisted,
         });
         return {
+            inline: tag.inline,
             label: tag.label,
-            items: tagVisibility.listedItems.map((item) => item.id),
             permalink: tag.permalink,
+            description: tag.description,
+            items: tagVisibility.listedItems.map((item) => item.id),
             pages: paginateBlogPosts({
                 blogPosts: tagVisibility.listedItems,
                 basePageUrl: tag.permalink,
@@ -116,7 +115,7 @@ async function parseBlogPostMarkdownFile({ filePath, parseFrontMatter, }) {
     }
 }
 const defaultReadingTime = ({ content, options }) => (0, reading_time_1.default)(content, options).minutes;
-async function processBlogSourceFile(blogSourceRelative, contentPaths, context, options, authorsMap) {
+async function processBlogSourceFile(blogSourceRelative, contentPaths, context, options, tagsFile, authorsMap) {
     const { siteConfig: { baseUrl, markdown: { parseFrontMatter }, }, siteDir, i18n, } = context;
     const { routeBasePath, tagsBasePath: tagsRouteBasePath, truncateMarker, showReadingTime, editUrl, } = options;
     // Lookup in localized folder in priority
@@ -190,12 +189,19 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
         }
         return undefined;
     }
-    const tagsBasePath = (0, utils_1.normalizeUrl)([
+    const tagsBaseRoutePath = (0, utils_1.normalizeUrl)([
         baseUrl,
         routeBasePath,
         tagsRouteBasePath,
     ]);
     const authors = (0, authors_1.getBlogPostAuthors)({ authorsMap, frontMatter, baseUrl });
+    const tags = (0, utils_1.normalizeTags)({
+        options,
+        source: blogSourceRelative,
+        frontMatterTags: frontMatter.tags,
+        tagsBaseRoutePath,
+        tagsFile,
+    });
     return {
         id: slug,
         metadata: {
@@ -205,7 +211,7 @@ async function processBlogSourceFile(blogSourceRelative, contentPaths, context,
             title,
             description,
             date,
-            tags: (0, utils_1.normalizeFrontMatterTags)(tagsBasePath, frontMatter.tags),
+            tags,
             readingTime: showReadingTime
                 ? options.readingTime({
                     content,
@@ -236,9 +242,10 @@ async function generateBlogPosts(contentPaths, context, options) {
         contentPaths,
         authorsMapPath: options.authorsMapPath,
     });
+    const tagsFile = await (0, utils_validation_1.getTagsFile)({ contentPaths, tags: options.tags });
     async function doProcessBlogSourceFile(blogSourceFile) {
         try {
-            return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, authorsMap);
+            return await processBlogSourceFile(blogSourceFile, contentPaths, context, options, tagsFile, authorsMap);
         }
         catch (err) {
             throw new Error(`Processing of blog source file path=${blogSourceFile} failed.`, { cause: err });

package/lib/index.js

@@ -11,12 +11,34 @@ const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
 const blogUtils_1 = require("./blogUtils");
 const footnoteIDFixer_1 = tslib_1.__importDefault(require("./remark/footnoteIDFixer"));
 const translations_1 = require("./translations");
 const feed_1 = require("./feed");
 const routes_1 = require("./routes");
 const PluginName = 'docusaurus-plugin-content-blog';
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to permalink is currently a mutable map passed to the mdx loader
+//  for link resolution
+//  see https://github.com/facebook/docusaurus/pull/10185
+function createSourceToPermalinkHelper() {
+    const sourceToPermalink = new Map();
+    function computeSourceToPermalink(content) {
+        return new Map(content.blogPosts.map(({ metadata: { source, permalink } }) => [
+            source,
+            permalink,
+        ]));
+    }
+    // Mutable map update :/
+    function update(content) {
+        sourceToPermalink.clear();
+        computeSourceToPermalink(content).forEach((value, key) => {
+            sourceToPermalink.set(key, value);
+        });
+    }
+    return { get: () => sourceToPermalink, update };
+}
 async function pluginContentBlog(context, options) {
     const { siteDir, siteConfig, generatedFilesDir, localizationDir, i18n: { currentLocale }, } = context;
     const router = siteConfig.future.experimental_router;
@@ -44,12 +66,21 @@ async function pluginContentBlog(context, options) {
         filePath: options.authorsMapPath,
         contentPaths,
     });
+    const sourceToPermalinkHelper = createSourceToPermalinkHelper();
     return {
         name: PluginName,
         getPathsToWatch() {
             const { include } = options;
             const contentMarkdownGlobs = (0, utils_1.getContentPathList)(contentPaths).flatMap((contentPath) => include.map((pattern) => `${contentPath}/${pattern}`));
-            return [authorsMapFilePath, ...contentMarkdownGlobs].filter(Boolean);
+            const tagsFilePaths = (0, utils_validation_1.getTagsFilePathsToWatch)({
+                contentPaths,
+                tags: options.tags,
+            });
+            return [
+                authorsMapFilePath,
+                ...tagsFilePaths,
+                ...contentMarkdownGlobs,
+            ].filter(Boolean);
         },
         getTranslationFiles() {
             return (0, translations_1.getTranslationFiles)(options);
@@ -117,6 +148,7 @@ async function pluginContentBlog(context, options) {
             };
         },
         async contentLoaded({ content, actions }) {
+            sourceToPermalinkHelper.update(content);
             await (0, routes_1.createAllRoutes)({
                 baseUrl,
                 content,
@@ -128,9 +160,8 @@ async function pluginContentBlog(context, options) {
         translateContent({ content, translationFiles }) {
             return (0, translations_1.translateContent)(content, translationFiles);
         },
-        configureWebpack(_config, isServer, utils, content) {
+        configureWebpack() {
             const { admonitions, rehypePlugins, remarkPlugins, truncateMarker, beforeDefaultRemarkPlugins, beforeDefaultRehypePlugins, } = options;
-            const sourceToPermalink = (0, blogUtils_1.getSourceToPermalink)(content.blogPosts);
             const contentDirs = (0, utils_1.getContentPathList)(contentPaths);
             function createMDXLoader() {
                 const loaderOptions = {
@@ -165,7 +196,7 @@ async function pluginContentBlog(context, options) {
                     resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
                         const permalink = (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
                             sourceFilePath,
-                            sourceToPermalink,
+                            sourceToPermalink: sourceToPermalinkHelper.get(),
                             siteDir,
                             contentPaths,
                         });

package/lib/options.js

@@ -42,6 +42,8 @@ exports.DEFAULT_OPTIONS = {
     showLastUpdateTime: false,
     showLastUpdateAuthor: false,
     processBlogPosts: async () => undefined,
+    onInlineTags: 'warn',
+    tags: undefined,
 };
 const PluginOptionSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
@@ -111,6 +113,13 @@ const PluginOptionSchema = utils_validation_1.Joi.object({
     processBlogPosts: utils_validation_1.Joi.function()
         .optional()
         .default(() => exports.DEFAULT_OPTIONS.processBlogPosts),
+    onInlineTags: utils_validation_1.Joi.string()
+        .equal('ignore', 'log', 'warn', 'throw')
+        .default(exports.DEFAULT_OPTIONS.onInlineTags),
+    tags: utils_validation_1.Joi.string()
+        .disallow('')
+        .allow(null, false)
+        .default(() => exports.DEFAULT_OPTIONS.tags),
 }).default(exports.DEFAULT_OPTIONS);
 function validateOptions({ validate, options, }) {
     const validatedOptions = validate(PluginOptionSchema, options);

package/lib/props.js

@@ -7,6 +7,7 @@ function toTagsProp({ blogTags }) {
         .map((tag) => ({
         label: tag.label,
         permalink: tag.permalink,
+        description: tag.description,
         count: tag.items.length,
     }));
 }
@@ -15,6 +16,7 @@ function toTagProp({ blogTagsListPath, tag, }) {
     return {
         label: tag.label,
         permalink: tag.permalink,
+        description: tag.description,
         allTagsPath: blogTagsListPath,
         count: tag.items.length,
         unlisted: tag.unlisted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-blog",
-  "version": "0.0.0-5961",
+  "version": "0.0.0-5963",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-blog.d.ts",
@@ -31,13 +31,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5961",
-    "@docusaurus/logger": "0.0.0-5961",
-    "@docusaurus/mdx-loader": "0.0.0-5961",
-    "@docusaurus/types": "0.0.0-5961",
-    "@docusaurus/utils": "0.0.0-5961",
-    "@docusaurus/utils-common": "0.0.0-5961",
-    "@docusaurus/utils-validation": "0.0.0-5961",
+    "@docusaurus/core": "0.0.0-5963",
+    "@docusaurus/logger": "0.0.0-5963",
+    "@docusaurus/mdx-loader": "0.0.0-5963",
+    "@docusaurus/types": "0.0.0-5963",
+    "@docusaurus/utils": "0.0.0-5963",
+    "@docusaurus/utils-common": "0.0.0-5963",
+    "@docusaurus/utils-validation": "0.0.0-5963",
     "cheerio": "^1.0.0-rc.12",
     "feed": "^4.2.2",
     "fs-extra": "^11.1.1",
@@ -59,5 +59,5 @@
   "devDependencies": {
     "@total-typescript/shoehorn": "^0.1.2"
   },
-  "gitHead": "ae17c4245467ae9c0c218dc375d4d059410f8622"
+  "gitHead": "e9090dc8a38a21043b0849887aa7d54d04c4af9f"
 }

package/src/blogUtils.ts

@@ -18,7 +18,6 @@ import {
   getFolderContainingFile,
   posixPath,
   Globby,
-  normalizeFrontMatterTags,
   groupTaggedItems,
   getTagVisibility,
   getFileCommitDate,
@@ -26,9 +25,12 @@ import {
   isUnlisted,
   isDraft,
   readLastUpdateData,
+  normalizeTags,
 } 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,
@@ -43,14 +45,6 @@ export function truncate(fileString: string, truncateMarker: RegExp): string {
   return fileString.split(truncateMarker, 1).shift()!;
 }
 
-export function getSourceToPermalink(blogPosts: BlogPost[]): {
-  [aliasedPath: string]: string;
-} {
-  return Object.fromEntries(
-    blogPosts.map(({metadata: {source, permalink}}) => [source, permalink]),
-  );
-}
-
 export function paginateBlogPosts({
   blogPosts,
   basePageUrl,
@@ -125,9 +119,11 @@ export function getBlogTags({
       isUnlisted: (item) => item.metadata.unlisted,
     });
     return {
+      inline: tag.inline,
       label: tag.label,
-      items: tagVisibility.listedItems.map((item) => item.id),
       permalink: tag.permalink,
+      description: tag.description,
+      items: tagVisibility.listedItems.map((item) => item.id),
       pages: paginateBlogPosts({
         blogPosts: tagVisibility.listedItems,
         basePageUrl: tag.permalink,
@@ -197,6 +193,7 @@ async function processBlogSourceFile(
   contentPaths: BlogContentPaths,
   context: LoadContext,
   options: PluginOptions,
+  tagsFile: TagsFile | null,
   authorsMap?: AuthorsMap,
 ): Promise<BlogPost | undefined> {
   const {
@@ -315,13 +312,21 @@ async function processBlogSourceFile(
     return undefined;
   }
 
-  const tagsBasePath = normalizeUrl([
+  const tagsBaseRoutePath = normalizeUrl([
     baseUrl,
     routeBasePath,
     tagsRouteBasePath,
   ]);
   const authors = getBlogPostAuthors({authorsMap, frontMatter, baseUrl});
 
+  const tags = normalizeTags({
+    options,
+    source: blogSourceRelative,
+    frontMatterTags: frontMatter.tags,
+    tagsBaseRoutePath,
+    tagsFile,
+  });
+
   return {
     id: slug,
     metadata: {
@@ -331,7 +336,7 @@ async function processBlogSourceFile(
       title,
       description,
       date,
-      tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
+      tags,
       readingTime: showReadingTime
         ? options.readingTime({
             content,
@@ -371,6 +376,8 @@ export async function generateBlogPosts(
     authorsMapPath: options.authorsMapPath,
   });
 
+  const tagsFile = await getTagsFile({contentPaths, tags: options.tags});
+
   async function doProcessBlogSourceFile(blogSourceFile: string) {
     try {
       return await processBlogSourceFile(
@@ -378,6 +385,7 @@ export async function generateBlogPosts(
         contentPaths,
         context,
         options,
+        tagsFile,
         authorsMap,
       );
     } catch (err) {

package/src/index.ts

@@ -19,9 +19,10 @@ import {
   getDataFilePath,
   DEFAULT_PLUGIN_ID,
   resolveMarkdownLinkPathname,
+  type SourceToPermalink,
 } from '@docusaurus/utils';
+import {getTagsFilePathsToWatch} from '@docusaurus/utils-validation';
 import {
-  getSourceToPermalink,
   getBlogTags,
   paginateBlogPosts,
   shouldBeListed,
@@ -49,6 +50,33 @@ import type {RuleSetUseItem} from 'webpack';
 
 const PluginName = 'docusaurus-plugin-content-blog';
 
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to permalink is currently a mutable map passed to the mdx loader
+//  for link resolution
+//  see https://github.com/facebook/docusaurus/pull/10185
+function createSourceToPermalinkHelper() {
+  const sourceToPermalink: SourceToPermalink = new Map();
+
+  function computeSourceToPermalink(content: BlogContent): SourceToPermalink {
+    return new Map(
+      content.blogPosts.map(({metadata: {source, permalink}}) => [
+        source,
+        permalink,
+      ]),
+    );
+  }
+
+  // Mutable map update :/
+  function update(content: BlogContent): void {
+    sourceToPermalink.clear();
+    computeSourceToPermalink(content).forEach((value, key) => {
+      sourceToPermalink.set(key, value);
+    });
+  }
+
+  return {get: () => sourceToPermalink, update};
+}
+
 export default async function pluginContentBlog(
   context: LoadContext,
   options: PluginOptions,
@@ -95,6 +123,8 @@ export default async function pluginContentBlog(
     contentPaths,
   });
 
+  const sourceToPermalinkHelper = createSourceToPermalinkHelper();
+
   return {
     name: PluginName,
 
@@ -104,9 +134,16 @@ export default async function pluginContentBlog(
         (contentPath) => include.map((pattern) => `${contentPath}/${pattern}`),
       );
 
-      return [authorsMapFilePath, ...contentMarkdownGlobs].filter(
-        Boolean,
-      ) as string[];
+      const tagsFilePaths = getTagsFilePathsToWatch({
+        contentPaths,
+        tags: options.tags,
+      });
+
+      return [
+        authorsMapFilePath,
+        ...tagsFilePaths,
+        ...contentMarkdownGlobs,
+      ].filter(Boolean) as string[];
     },
 
     getTranslationFiles() {
@@ -193,6 +230,8 @@ export default async function pluginContentBlog(
     },
 
     async contentLoaded({content, actions}) {
+      sourceToPermalinkHelper.update(content);
+
       await createAllRoutes({
         baseUrl,
         content,
@@ -206,7 +245,7 @@ export default async function pluginContentBlog(
       return translateContent(content, translationFiles);
     },
 
-    configureWebpack(_config, isServer, utils, content) {
+    configureWebpack() {
       const {
         admonitions,
         rehypePlugins,
@@ -216,7 +255,6 @@ export default async function pluginContentBlog(
         beforeDefaultRehypePlugins,
       } = options;
 
-      const sourceToPermalink = getSourceToPermalink(content.blogPosts);
       const contentDirs = getContentPathList(contentPaths);
 
       function createMDXLoader(): RuleSetUseItem {
@@ -263,7 +301,7 @@ export default async function pluginContentBlog(
           resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
             const permalink = resolveMarkdownLinkPathname(linkPathname, {
               sourceFilePath,
-              sourceToPermalink,
+              sourceToPermalink: sourceToPermalinkHelper.get(),
               siteDir,
               contentPaths,
             });

package/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({

package/src/plugin-content-blog.d.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 /// <reference types="@docusaurus/module-type-aliases" />
 
 declare module '@docusaurus/plugin-content-blog' {
@@ -12,9 +11,10 @@ declare module '@docusaurus/plugin-content-blog' {
   import type {MDXOptions} from '@docusaurus/mdx-loader';
   import type {
     FrontMatterTag,
-    Tag,
+    TagMetadata,
     LastUpdateData,
     FrontMatterLastUpdate,
+    TagsPluginOptions,
   } from '@docusaurus/utils';
   import type {DocusaurusConfig, Plugin, LoadContext} from '@docusaurus/types';
   import type {Item as FeedItem} from 'feed';
@@ -236,7 +236,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     /** Front matter, as-is. */
     readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
     /** Tags, normalized. */
-    readonly tags: Tag[];
+    readonly tags: TagMetadata[];
     /**
      * Marks the post as unlisted and visibly hides it unless directly accessed.
      */
@@ -345,103 +345,104 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
   /**
    * Plugin options after normalization.
    */
-  export type PluginOptions = MDXOptions & {
-    /** Plugin ID. */
-    id?: string;
-    /**
-     * Path to the blog content directory on the file system, relative to site
-     * directory.
-     */
-    path: string;
-    /**
-     * URL route for the blog section of your site. **DO NOT** include a
-     * trailing slash. Use `/` to put the blog at root path.
-     */
-    routeBasePath: string;
-    /**
-     * URL route for the tags section of your blog. Will be appended to
-     * `routeBasePath`.
-     */
-    tagsBasePath: string;
-    /**
-     * URL route for the pages section of your blog. Will be appended to
-     * `routeBasePath`.
-     */
-    pageBasePath: string;
-    /**
-     * URL route for the archive section of your blog. Will be appended to
-     * `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to
-     * disable generation of archive.
-     */
-    archiveBasePath: string | null;
-    /**
-     * Array of glob patterns matching Markdown files to be built, relative to
-     * the content path.
-     */
-    include: string[];
-    /**
-     * Array of glob patterns matching Markdown files to be excluded. Serves as
-     * refinement based on the `include` option.
-     */
-    exclude: string[];
-    /**
-     *  Number of posts to show per page in the listing page. Use `'ALL'` to
-     * display all posts on one listing page.
-     */
-    postsPerPage: number | 'ALL';
-    /** Root component of the blog listing page. */
-    blogListComponent: string;
-    /** Root component of each blog post page. */
-    blogPostComponent: string;
-    /** Root component of the tags list page. */
-    blogTagsListComponent: string;
-    /** Root component of the "posts containing tag" page. */
-    blogTagsPostsComponent: string;
-    /** Root component of the blog archive page. */
-    blogArchiveComponent: string;
-    /** Blog page title for better SEO. */
-    blogTitle: string;
-    /** Blog page meta description for better SEO. */
-    blogDescription: string;
-    /**
-     * Number of blog post elements to show in the blog sidebar. `'ALL'` to show
-     * all blog posts; `0` to disable.
-     */
-    blogSidebarCount: number | 'ALL';
-    /** Title of the blog sidebar. */
-    blogSidebarTitle: string;
-    /** Truncate marker marking where the summary ends. */
-    truncateMarker: RegExp;
-    /** Show estimated reading time for the blog post. */
-    showReadingTime: boolean;
-    /** Blog feed. */
-    feedOptions: FeedOptions;
-    /**
-     * Base URL to edit your site. The final URL is computed by `editUrl +
-     * relativePostPath`. Using a function allows more nuanced control for each
-     * file. Omitting this variable entirely will disable edit links.
-     */
-    editUrl?: string | EditUrlFunction;
-    /**
-     * The edit URL will target the localized file, instead of the original
-     * unlocalized file. Ignored when `editUrl` is a function.
-     */
-    editLocalizedFiles?: boolean;
-    /** Path to the authors map file, relative to the blog content directory. */
-    authorsMapPath: string;
-    /** A callback to customize the reading time number displayed. */
-    readingTime: ReadingTimeFunctionOption;
-    /** Governs the direction of blog post sorting. */
-    sortPosts: 'ascending' | 'descending';
-    /**	Whether to display the last date the doc was updated. */
-    showLastUpdateTime: boolean;
-    /** Whether to display the author who last updated the doc. */
-    showLastUpdateAuthor: boolean;
-    /** An optional function which can be used to transform blog posts
-     *  (filter, modify, delete, etc...).
-     */
-    processBlogPosts: ProcessBlogPostsFn;
-  };
+  export type PluginOptions = MDXOptions &
+    TagsPluginOptions & {
+      /** Plugin ID. */
+      id?: string;
+      /**
+       * Path to the blog content directory on the file system, relative to site
+       * directory.
+       */
+      path: string;
+      /**
+       * URL route for the blog section of your site. **DO NOT** include a
+       * trailing slash. Use `/` to put the blog at root path.
+       */
+      routeBasePath: string;
+      /**
+       * URL route for the tags section of your blog. Will be appended to
+       * `routeBasePath`.
+       */
+      tagsBasePath: string;
+      /**
+       * URL route for the pages section of your blog. Will be appended to
+       * `routeBasePath`.
+       */
+      pageBasePath: string;
+      /**
+       * URL route for the archive section of your blog. Will be appended to
+       * `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to
+       * disable generation of archive.
+       */
+      archiveBasePath: string | null;
+      /**
+       * Array of glob patterns matching Markdown files to be built, relative to
+       * the content path.
+       */
+      include: string[];
+      /**
+       * Array of glob patterns matching Markdown files to be excluded. Serves as
+       * refinement based on the `include` option.
+       */
+      exclude: string[];
+      /**
+       *  Number of posts to show per page in the listing page. Use `'ALL'` to
+       * display all posts on one listing page.
+       */
+      postsPerPage: number | 'ALL';
+      /** Root component of the blog listing page. */
+      blogListComponent: string;
+      /** Root component of each blog post page. */
+      blogPostComponent: string;
+      /** Root component of the tags list page. */
+      blogTagsListComponent: string;
+      /** Root component of the "posts containing tag" page. */
+      blogTagsPostsComponent: string;
+      /** Root component of the blog archive page. */
+      blogArchiveComponent: string;
+      /** Blog page title for better SEO. */
+      blogTitle: string;
+      /** Blog page meta description for better SEO. */
+      blogDescription: string;
+      /**
+       * Number of blog post elements to show in the blog sidebar. `'ALL'` to show
+       * all blog posts; `0` to disable.
+       */
+      blogSidebarCount: number | 'ALL';
+      /** Title of the blog sidebar. */
+      blogSidebarTitle: string;
+      /** Truncate marker marking where the summary ends. */
+      truncateMarker: RegExp;
+      /** Show estimated reading time for the blog post. */
+      showReadingTime: boolean;
+      /** Blog feed. */
+      feedOptions: FeedOptions;
+      /**
+       * Base URL to edit your site. The final URL is computed by `editUrl +
+       * relativePostPath`. Using a function allows more nuanced control for each
+       * file. Omitting this variable entirely will disable edit links.
+       */
+      editUrl?: string | EditUrlFunction;
+      /**
+       * The edit URL will target the localized file, instead of the original
+       * unlocalized file. Ignored when `editUrl` is a function.
+       */
+      editLocalizedFiles?: boolean;
+      /** Path to the authors map file, relative to the blog content directory. */
+      authorsMapPath: string;
+      /** A callback to customize the reading time number displayed. */
+      readingTime: ReadingTimeFunctionOption;
+      /** Governs the direction of blog post sorting. */
+      sortPosts: 'ascending' | 'descending';
+      /**	Whether to display the last date the doc was updated. */
+      showLastUpdateTime: boolean;
+      /** Whether to display the author who last updated the doc. */
+      showLastUpdateAuthor: boolean;
+      /** An optional function which can be used to transform blog posts
+       *  (filter, modify, delete, etc...).
+       */
+      processBlogPosts: ProcessBlogPostsFn;
+    };
 
   /**
    * Feed options, as provided by user config. `type` accepts `all` as shortcut
@@ -494,7 +495,7 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     [permalink: string]: BlogTag;
   };
 
-  export type BlogTag = Tag & {
+  export type BlogTag = TagMetadata & {
     /** Blog post permalinks. */
     items: string[];
     pages: BlogPaginated[];

package/src/props.ts

@@ -13,6 +13,7 @@ export function toTagsProp({blogTags}: {blogTags: BlogTags}): TagsListItem[] {
     .map((tag) => ({
       label: tag.label,
       permalink: tag.permalink,
+      description: tag.description,
       count: tag.items.length,
     }));
 }
@@ -27,6 +28,7 @@ export function toTagProp({
   return {
     label: tag.label,
     permalink: tag.permalink,
+    description: tag.description,
     allTagsPath: blogTagsListPath,
     count: tag.items.length,
     unlisted: tag.unlisted,