@docusaurus/plugin-content-blog 0.0.0-5957 → 0.0.0-5962

package/lib/blogUtils.js

@@ -14,6 +14,7 @@ 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) {
@@ -67,9 +68,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 +119,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 +193,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 +215,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 +246,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,6 +11,7 @@ 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");
@@ -49,7 +50,15 @@ async function pluginContentBlog(context, options) {
         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);

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-5957",
+  "version": "0.0.0-5962",
   "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-5957",
-    "@docusaurus/logger": "0.0.0-5957",
-    "@docusaurus/mdx-loader": "0.0.0-5957",
-    "@docusaurus/types": "0.0.0-5957",
-    "@docusaurus/utils": "0.0.0-5957",
-    "@docusaurus/utils-common": "0.0.0-5957",
-    "@docusaurus/utils-validation": "0.0.0-5957",
+    "@docusaurus/core": "0.0.0-5962",
+    "@docusaurus/logger": "0.0.0-5962",
+    "@docusaurus/mdx-loader": "0.0.0-5962",
+    "@docusaurus/types": "0.0.0-5962",
+    "@docusaurus/utils": "0.0.0-5962",
+    "@docusaurus/utils-common": "0.0.0-5962",
+    "@docusaurus/utils-validation": "0.0.0-5962",
     "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": "edb3a453b0b3a853eadfc4e9ec44d47ea76d5002"
+  "gitHead": "35386a1d384d8e8757ef9f993b84dd5accc00e97"
 }

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,
@@ -125,9 +127,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 +201,7 @@ async function processBlogSourceFile(
   contentPaths: BlogContentPaths,
   context: LoadContext,
   options: PluginOptions,
+  tagsFile: TagsFile | null,
   authorsMap?: AuthorsMap,
 ): Promise<BlogPost | undefined> {
   const {
@@ -315,13 +320,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 +344,7 @@ async function processBlogSourceFile(
       title,
       description,
       date,
-      tags: normalizeFrontMatterTags(tagsBasePath, frontMatter.tags),
+      tags,
       readingTime: showReadingTime
         ? options.readingTime({
             content,
@@ -371,6 +384,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 +393,7 @@ export async function generateBlogPosts(
         contentPaths,
         context,
         options,
+        tagsFile,
         authorsMap,
       );
     } catch (err) {

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   DEFAULT_PLUGIN_ID,
   resolveMarkdownLinkPathname,
 } from '@docusaurus/utils';
+import {getTagsFilePathsToWatch} from '@docusaurus/utils-validation';
 import {
   getSourceToPermalink,
   getBlogTags,
@@ -104,9 +105,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() {

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,