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

package/lib/docs.d.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference path="../src/plugin-content-docs.d.ts" />
+import type { TagsFile } from '@docusaurus/utils';
 import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
 import type { LoadContext } from '@docusaurus/types';
 import type { SidebarsUtils } from './sidebars/utils';
@@ -18,6 +19,7 @@ export declare function processDocMetadata(args: {
     context: LoadContext;
     options: MetadataOptions;
     env: DocEnv;
+    tagsFile: TagsFile | null;
 }): Promise<DocMetadataBase>;
 export declare function addDocNavigation({ docs, sidebarsUtils, }: {
     docs: DocMetadataBase[];

package/lib/docs.js

@@ -31,7 +31,7 @@ async function readVersionDocs(versionMetadata, options) {
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source)));
 }
 exports.readVersionDocs = readVersionDocs;
-async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
+async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, tagsFile, }) {
     const { source, content, contentPath, filePath } = docFile;
     const { siteDir, siteConfig: { markdown: { parseFrontMatter }, }, } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = await (0, utils_1.parseMarkdownFile)({
@@ -108,6 +108,13 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     }
     const draft = (0, utils_1.isDraft)({ env, frontMatter });
     const unlisted = (0, utils_1.isUnlisted)({ env, frontMatter });
+    const tags = (0, utils_1.normalizeTags)({
+        options,
+        source,
+        frontMatterTags: frontMatter.tags,
+        tagsBaseRoutePath: versionMetadata.tagsPath,
+        tagsFile,
+    });
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
     // Adding properties to object after instantiation will cause hidden
@@ -123,7 +130,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
         draft,
         unlisted,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
-        tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
+        tags,
         version: versionMetadata.versionName,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,

package/lib/index.js

@@ -12,6 +12,7 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebars_1 = require("./sidebars");
 const generator_1 = require("./sidebars/generator");
 const docs_1 = require("./docs");
@@ -61,6 +62,10 @@ async function pluginContentDocs(context, options) {
             function getVersionPathsToWatch(version) {
                 const result = [
                     ...options.include.flatMap((pattern) => (0, utils_1.getContentPathList)(version).map((docsDirPath) => `${docsDirPath}/${pattern}`)),
+                    ...(0, utils_validation_1.getTagsFilePathsToWatch)({
+                        contentPaths: version,
+                        tags: options.tags,
+                    }),
                     `${version.contentPath}/**/${generator_1.CategoryMetadataFilenamePattern}`,
                 ];
                 if (typeof version.sidebarFilePath === 'string') {
@@ -71,7 +76,7 @@ async function pluginContentDocs(context, options) {
             return versionsMetadata.flatMap(getVersionPathsToWatch);
         },
         async loadContent() {
-            async function loadVersionDocsBase(versionMetadata) {
+            async function loadVersionDocsBase(versionMetadata, tagsFile) {
                 const docFiles = await (0, docs_1.readVersionDocs)(versionMetadata, options);
                 if (docFiles.length === 0) {
                     throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(siteDir, versionMetadata.contentPath)}".`);
@@ -83,12 +88,17 @@ async function pluginContentDocs(context, options) {
                         context,
                         options,
                         env,
+                        tagsFile,
                     });
                 }
                 return Promise.all(docFiles.map(processVersionDoc));
             }
             async function doLoadVersion(versionMetadata) {
-                const docsBase = await loadVersionDocsBase(versionMetadata);
+                const tagsFile = await (0, utils_validation_1.getTagsFile)({
+                    contentPaths: versionMetadata,
+                    tags: options.tags,
+                });
+                const docsBase = await loadVersionDocsBase(versionMetadata, tagsFile);
                 // TODO we only ever need draftIds in further code, not full draft items
                 // To simplify and prevent mistakes, avoid exposing draft
                 // replace draft=>draftIds in content loaded

package/lib/options.js

@@ -44,6 +44,8 @@ exports.DEFAULT_OPTIONS = {
     sidebarCollapsible: true,
     sidebarCollapsed: true,
     breadcrumbs: true,
+    onInlineTags: 'warn',
+    tags: undefined,
 };
 const VersionOptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().allow('').optional(),
@@ -100,6 +102,13 @@ const OptionsSchema = utils_validation_1.Joi.object({
     lastVersion: utils_validation_1.Joi.string().optional(),
     versions: VersionsOptionsSchema,
     breadcrumbs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.breadcrumbs),
+    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),
 });
 function validateOptions({ validate, options: userOptions, }) {
     let options = userOptions;

package/lib/props.js

@@ -134,6 +134,7 @@ function toTagDocListProp({ allTagsPath, tag, docs, }) {
     return {
         label: tag.label,
         permalink: tag.permalink,
+        description: tag.description,
         allTagsPath,
         count: tag.docIds.length,
         items: toDocListProp(),
@@ -147,6 +148,7 @@ function toTagsListTagsProp(versionTags) {
         .map((tagValue) => ({
         label: tagValue.label,
         permalink: tagValue.permalink,
+        description: tagValue.description,
         count: tagValue.docIds.length,
     }));
 }

package/lib/routes.js

@@ -12,7 +12,6 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
-const tags_1 = require("./tags");
 function createDocRouteMetadata(docMeta) {
     return {
         sourceFilePath: (0, utils_1.aliasedSitePathToRelativePath)(docMeta.source),
@@ -74,12 +73,30 @@ async function buildVersionSidebarRoute(param) {
         routes: subRoutes,
     };
 }
+function getVersionTags(docs) {
+    const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagDocs }) => {
+        const tagVisibility = (0, utils_1.getTagVisibility)({
+            items: tagDocs,
+            isUnlisted: (item) => item.unlisted,
+        });
+        return {
+            inline: tag.inline,
+            label: tag.label,
+            permalink: tag.permalink,
+            description: tag.description,
+            docIds: tagVisibility.listedItems.map((item) => item.id),
+            unlisted: tagVisibility.unlisted,
+        };
+    });
+}
 async function buildVersionTagsRoutes(param) {
     const { version, options } = param;
-    const versionTags = (0, tags_1.getVersionTags)(version.docs);
+    const versionTags = getVersionTags(version.docs);
     async function buildTagsListRoute() {
+        const tags = (0, props_1.toTagsListTagsProp)(versionTags);
         // Don't create a tags list page if there's no tag
-        if (Object.keys(versionTags).length === 0) {
+        if (tags.length === 0) {
             return null;
         }
         return {
@@ -87,7 +104,7 @@ async function buildVersionTagsRoutes(param) {
             exact: true,
             component: options.docTagsListComponent,
             props: {
-                tags: (0, props_1.toTagsListTagsProp)(versionTags),
+                tags,
             },
         };
     }

package/lib/types.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference path="../src/plugin-content-docs.d.ts" />
-import type { Tag } from '@docusaurus/utils';
+import type { TagMetadata } from '@docusaurus/utils';
 import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export type DocFile = {
@@ -17,7 +17,7 @@ export type DocFile = {
 export type SourceToPermalink = {
     [source: string]: string;
 };
-export type VersionTag = Tag & {
+export type VersionTag = TagMetadata & {
     /** All doc ids having this tag. */
     docIds: string[];
     unlisted: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5957",
+  "version": "0.0.0-5962",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5957",
-    "@docusaurus/logger": "0.0.0-5957",
-    "@docusaurus/mdx-loader": "0.0.0-5957",
-    "@docusaurus/module-type-aliases": "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/module-type-aliases": "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",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -66,5 +66,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "edb3a453b0b3a853eadfc4e9ec44d47ea76d5002"
+  "gitHead": "35386a1d384d8e8757ef9f993b84dd5accc00e97"
 }

package/src/docs.ts

@@ -17,15 +17,16 @@ import {
   parseMarkdownFile,
   posixPath,
   Globby,
-  normalizeFrontMatterTags,
   isUnlisted,
   isDraft,
   readLastUpdateData,
+  normalizeTags,
 } from '@docusaurus/utils';
 import {validateDocFrontMatter} from './frontMatter';
 import getSlug from './slug';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
+import type {TagsFile} from '@docusaurus/utils';
 import type {
   MetadataOptions,
   PluginOptions,
@@ -82,12 +83,14 @@ async function doProcessDocMetadata({
   context,
   options,
   env,
+  tagsFile,
 }: {
   docFile: DocFile;
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
+  tagsFile: TagsFile | null;
 }): Promise<DocMetadataBase> {
   const {source, content, contentPath, filePath} = docFile;
   const {
@@ -206,6 +209,14 @@ async function doProcessDocMetadata({
   const draft = isDraft({env, frontMatter});
   const unlisted = isUnlisted({env, frontMatter});
 
+  const tags = normalizeTags({
+    options,
+    source,
+    frontMatterTags: frontMatter.tags,
+    tagsBaseRoutePath: versionMetadata.tagsPath,
+    tagsFile,
+  });
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
@@ -221,7 +232,7 @@ async function doProcessDocMetadata({
     draft,
     unlisted,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
-    tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
+    tags,
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -236,6 +247,7 @@ export async function processDocMetadata(args: {
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
+  tagsFile: TagsFile | null;
 }): Promise<DocMetadataBase> {
   try {
     return await doProcessDocMetadata(args);

package/src/index.ts

@@ -20,6 +20,10 @@ import {
   resolveMarkdownLinkPathname,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
+import {
+  getTagsFile,
+  getTagsFilePathsToWatch,
+} from '@docusaurus/utils-validation';
 import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
 import {
@@ -43,6 +47,7 @@ import {
 } from './translations';
 import {createAllRoutes} from './routes';
 import {createSidebarsUtils} from './sidebars/utils';
+import type {TagsFile} from '@docusaurus/utils';
 import type {Options as MDXLoaderOptions} from '@docusaurus/mdx-loader';
 
 import type {
@@ -119,6 +124,10 @@ export default async function pluginContentDocs(
               (docsDirPath) => `${docsDirPath}/${pattern}`,
             ),
           ),
+          ...getTagsFilePathsToWatch({
+            contentPaths: version,
+            tags: options.tags,
+          }),
           `${version.contentPath}/**/${CategoryMetadataFilenamePattern}`,
         ];
         if (typeof version.sidebarFilePath === 'string') {
@@ -133,6 +142,7 @@ export default async function pluginContentDocs(
     async loadContent() {
       async function loadVersionDocsBase(
         versionMetadata: VersionMetadata,
+        tagsFile: TagsFile | null,
       ): Promise<DocMetadataBase[]> {
         const docFiles = await readVersionDocs(versionMetadata, options);
         if (docFiles.length === 0) {
@@ -152,6 +162,7 @@ export default async function pluginContentDocs(
             context,
             options,
             env,
+            tagsFile,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -160,8 +171,14 @@ export default async function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
+        const tagsFile = await getTagsFile({
+          contentPaths: versionMetadata,
+          tags: options.tags,
+        });
+
         const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
+          tagsFile,
         );
 
         // TODO we only ever need draftIds in further code, not full draft items

package/src/options.ts

@@ -54,6 +54,8 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   sidebarCollapsible: true,
   sidebarCollapsed: true,
   breadcrumbs: true,
+  onInlineTags: 'warn',
+  tags: undefined,
 };
 
 const VersionOptionsSchema = Joi.object({
@@ -140,6 +142,13 @@ const OptionsSchema = Joi.object<PluginOptions>({
   lastVersion: Joi.string().optional(),
   versions: VersionsOptionsSchema,
   breadcrumbs: Joi.bool().default(DEFAULT_OPTIONS.breadcrumbs),
+  onInlineTags: Joi.string()
+    .equal('ignore', 'log', 'warn', 'throw')
+    .default(DEFAULT_OPTIONS.onInlineTags),
+  tags: Joi.string()
+    .disallow('')
+    .allow(null, false)
+    .default(() => DEFAULT_OPTIONS.tags),
 });
 
 export function validateOptions({

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

@@ -15,9 +15,10 @@ declare module '@docusaurus/plugin-content-docs' {
     FrontMatterTag,
     TagsListItem,
     TagModule,
-    Tag,
     FrontMatterLastUpdate,
     LastUpdateData,
+    TagMetadata,
+    TagsPluginOptions,
   } from '@docusaurus/utils';
   import type {Plugin, LoadContext} from '@docusaurus/types';
   import type {Overwrite, Required} from 'utility-types';
@@ -64,7 +65,7 @@ declare module '@docusaurus/plugin-content-docs' {
     locale: string;
   }) => string | undefined;
 
-  export type MetadataOptions = {
+  export type MetadataOptions = TagsPluginOptions & {
     /**
      * URL route for the docs section of your site. **DO NOT** include a
      * trailing slash. Use `/` for shipping docs without base path.
@@ -446,7 +447,7 @@ declare module '@docusaurus/plugin-content-docs' {
      */
     editUrl?: string | null;
     /** Tags, normalized. */
-    tags: Tag[];
+    tags: TagMetadata[];
     /** Front matter, as-is. */
     frontMatter: DocFrontMatter & {[key: string]: unknown};
   };

package/src/props.ts

@@ -206,6 +206,7 @@ export function toTagDocListProp({
   return {
     label: tag.label,
     permalink: tag.permalink,
+    description: tag.description,
     allTagsPath,
     count: tag.docIds.length,
     items: toDocListProp(),
@@ -221,6 +222,7 @@ export function toTagsListTagsProp(
     .map((tagValue) => ({
       label: tagValue.label,
       permalink: tagValue.permalink,
+      description: tagValue.description,
       count: tagValue.docIds.length,
     }));
 }

package/src/routes.ts

@@ -11,19 +11,20 @@ import {
   docuHash,
   normalizeUrl,
   aliasedSitePathToRelativePath,
+  groupTaggedItems,
+  getTagVisibility,
 } from '@docusaurus/utils';
 import {
   toTagDocListProp,
   toTagsListTagsProp,
   toVersionMetadataProp,
 } from './props';
-import {getVersionTags} from './tags';
 import type {
   PluginContentLoadedActions,
   RouteConfig,
   RouteMetadata,
 } from '@docusaurus/types';
-import type {FullVersion, VersionTag} from './types';
+import type {FullVersion, VersionTag, VersionTags} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
   DocMetadata,
@@ -112,6 +113,23 @@ async function buildVersionSidebarRoute(param: BuildVersionRoutesParam) {
     routes: subRoutes,
   };
 }
+function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return _.mapValues(groups, ({tag, items: tagDocs}) => {
+    const tagVisibility = getTagVisibility({
+      items: tagDocs,
+      isUnlisted: (item) => item.unlisted,
+    });
+    return {
+      inline: tag.inline,
+      label: tag.label,
+      permalink: tag.permalink,
+      description: tag.description,
+      docIds: tagVisibility.listedItems.map((item) => item.id),
+      unlisted: tagVisibility.unlisted,
+    };
+  });
+}
 
 async function buildVersionTagsRoutes(
   param: BuildVersionRoutesParam,
@@ -120,8 +138,9 @@ async function buildVersionTagsRoutes(
   const versionTags = getVersionTags(version.docs);
 
   async function buildTagsListRoute(): Promise<RouteConfig | null> {
+    const tags = toTagsListTagsProp(versionTags);
     // Don't create a tags list page if there's no tag
-    if (Object.keys(versionTags).length === 0) {
+    if (tags.length === 0) {
       return null;
     }
     return {
@@ -129,7 +148,7 @@ async function buildVersionTagsRoutes(
       exact: true,
       component: options.docTagsListComponent,
       props: {
-        tags: toTagsListTagsProp(versionTags),
+        tags,
       },
     };
   }

package/src/types.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {Tag} from '@docusaurus/utils';
+import type {TagMetadata} from '@docusaurus/utils';
 import type {
   LoadedVersion,
   CategoryGeneratedIndexMetadata,
@@ -23,7 +23,7 @@ export type SourceToPermalink = {
   [source: string]: string;
 };
 
-export type VersionTag = Tag & {
+export type VersionTag = TagMetadata & {
   /** All doc ids having this tag. */
   docIds: string[];
   unlisted: boolean;

package/lib/tags.d.ts

@@ -1,10 +0,0 @@
-/**
- * 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.
- */
-/// <reference path="../src/plugin-content-docs.d.ts" />
-import type { VersionTags } from './types';
-import type { DocMetadata } from '@docusaurus/plugin-content-docs';
-export declare function getVersionTags(docs: DocMetadata[]): VersionTags;

package/lib/tags.js

@@ -1,28 +0,0 @@
-"use strict";
-/**
- * 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.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersionTags = void 0;
-const tslib_1 = require("tslib");
-const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const utils_1 = require("@docusaurus/utils");
-function getVersionTags(docs) {
-    const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
-    return lodash_1.default.mapValues(groups, ({ tag, items: tagDocs }) => {
-        const tagVisibility = (0, utils_1.getTagVisibility)({
-            items: tagDocs,
-            isUnlisted: (item) => item.unlisted,
-        });
-        return {
-            label: tag.label,
-            docIds: tagVisibility.listedItems.map((item) => item.id),
-            permalink: tag.permalink,
-            unlisted: tagVisibility.unlisted,
-        };
-    });
-}
-exports.getVersionTags = getVersionTags;

package/src/tags.ts

@@ -1,27 +0,0 @@
-/**
- * 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.
- */
-
-import _ from 'lodash';
-import {getTagVisibility, groupTaggedItems} from '@docusaurus/utils';
-import type {VersionTags} from './types';
-import type {DocMetadata} from '@docusaurus/plugin-content-docs';
-
-export function getVersionTags(docs: DocMetadata[]): VersionTags {
-  const groups = groupTaggedItems(docs, (doc) => doc.tags);
-  return _.mapValues(groups, ({tag, items: tagDocs}) => {
-    const tagVisibility = getTagVisibility({
-      items: tagDocs,
-      isUnlisted: (item) => item.unlisted,
-    });
-    return {
-      label: tag.label,
-      docIds: tagVisibility.listedItems.map((item) => item.id),
-      permalink: tag.permalink,
-      unlisted: tagVisibility.unlisted,
-    };
-  });
-}