@docusaurus/plugin-content-docs 3.3.2 → 3.4.0

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");
@@ -22,6 +23,25 @@ const globalData_1 = require("./globalData");
 const translations_1 = require("./translations");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
+// 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) {
+        const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+        return new Map(allDocs.map(({ 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 pluginContentDocs(context, options) {
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
     // Mutate options to resolve sidebar path according to siteDir
@@ -36,6 +56,7 @@ async function pluginContentDocs(context, options) {
     const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(path_1.default.relative(pluginDataDirRoot, source))}`;
     // TODO env should be injected into all plugins
     const env = process.env.NODE_ENV;
+    const sourceToPermalinkHelper = createSourceToPermalinkHelper();
     return {
         name: 'docusaurus-plugin-content-docs',
         extendCli(cli) {
@@ -61,6 +82,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 +96,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 +108,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
@@ -144,6 +174,7 @@ async function pluginContentDocs(context, options) {
             return (0, translations_1.translateLoadedContent)(content, translationFiles);
         },
         async contentLoaded({ content, actions }) {
+            sourceToPermalinkHelper.update(content);
             const versions = content.loadedVersions.map(versions_1.toFullVersion);
             await (0, routes_1.createAllRoutes)({
                 baseUrl,
@@ -160,57 +191,49 @@ async function pluginContentDocs(context, options) {
         },
         configureWebpack(_config, isServer, utils, content) {
             const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
-            function getSourceToPermalink() {
-                const allDocs = content.loadedVersions.flatMap((v) => v.docs);
-                return Object.fromEntries(allDocs.map(({ source, permalink }) => [source, permalink]));
-            }
-            const docsMarkdownOptions = {
-                siteDir,
-                sourceToPermalink: getSourceToPermalink(),
-                versionsMetadata,
-                onBrokenMarkdownLink: (brokenMarkdownLink) => {
-                    logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
-                },
-            };
-            function createMDXLoaderRule() {
-                const contentDirs = versionsMetadata
-                    .flatMap(utils_1.getContentPathList)
-                    // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
-                    .map(utils_1.addTrailingPathSeparator);
+            const contentDirs = versionsMetadata
+                .flatMap(utils_1.getContentPathList)
+                // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+                .map(utils_1.addTrailingPathSeparator);
+            function createMDXLoader() {
+                const loaderOptions = {
+                    admonitions: options.admonitions,
+                    remarkPlugins,
+                    rehypePlugins,
+                    beforeDefaultRehypePlugins,
+                    beforeDefaultRemarkPlugins,
+                    staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
+                    siteDir,
+                    isMDXPartial: (0, utils_1.createAbsoluteFilePathMatcher)(options.exclude, contentDirs),
+                    metadataPath: (mdxPath) => {
+                        // Note that metadataPath must be the same/in-sync as
+                        // the path from createData for each MDX.
+                        const aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                        return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
+                    },
+                    // Assets allow to convert some relative images paths to
+                    // require(...) calls
+                    createAssets: ({ frontMatter }) => ({
+                        image: frontMatter.image,
+                    }),
+                    markdownConfig: siteConfig.markdown,
+                    resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
+                        const version = (0, versions_1.getVersionFromSourceFilePath)(sourceFilePath, content.loadedVersions);
+                        const permalink = (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
+                            sourceFilePath,
+                            sourceToPermalink: sourceToPermalinkHelper.get(),
+                            siteDir,
+                            contentPaths: version,
+                        });
+                        if (permalink === null) {
+                            logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
+                        }
+                        return permalink;
+                    },
+                };
                 return {
-                    test: /\.mdx?$/i,
-                    include: contentDirs,
-                    use: [
-                        {
-                            loader: require.resolve('@docusaurus/mdx-loader'),
-                            options: {
-                                admonitions: options.admonitions,
-                                remarkPlugins,
-                                rehypePlugins,
-                                beforeDefaultRehypePlugins,
-                                beforeDefaultRemarkPlugins,
-                                staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
-                                siteDir,
-                                isMDXPartial: (0, utils_1.createAbsoluteFilePathMatcher)(options.exclude, contentDirs),
-                                metadataPath: (mdxPath) => {
-                                    // Note that metadataPath must be the same/in-sync as
-                                    // the path from createData for each MDX.
-                                    const aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
-                                    return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
-                                },
-                                // Assets allow to convert some relative images paths to
-                                // require(...) calls
-                                createAssets: ({ frontMatter, }) => ({
-                                    image: frontMatter.image,
-                                }),
-                                markdownConfig: siteConfig.markdown,
-                            },
-                        },
-                        {
-                            loader: path_1.default.resolve(__dirname, './markdown/index.js'),
-                            options: docsMarkdownOptions,
-                        },
-                    ].filter(Boolean),
+                    loader: require.resolve('@docusaurus/mdx-loader'),
+                    options: loaderOptions,
                 };
             }
             return {
@@ -225,7 +248,13 @@ async function pluginContentDocs(context, options) {
                     },
                 },
                 module: {
-                    rules: [createMDXLoaderRule()],
+                    rules: [
+                        {
+                            test: /\.mdx?$/i,
+                            include: contentDirs,
+                            use: [createMDXLoader()],
+                        },
+                    ],
                 },
             };
         },

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,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference path="../src/plugin-content-docs.d.ts" />
-import type { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
-import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { TagMetadata } from '@docusaurus/utils';
+import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export type DocFile = {
     contentPath: string;
@@ -14,10 +14,7 @@ export type DocFile = {
     source: string;
     content: string;
 };
-export type SourceToPermalink = {
-    [source: string]: string;
-};
-export type VersionTag = Tag & {
+export type VersionTag = TagMetadata & {
     /** All doc ids having this tag. */
     docIds: string[];
     unlisted: boolean;
@@ -29,10 +26,3 @@ export type FullVersion = LoadedVersion & {
     sidebarsUtils: SidebarsUtils;
     categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-export type DocsMarkdownOption = {
-    versionsMetadata: VersionMetadata[];
-    siteDir: string;
-    sourceToPermalink: SourceToPermalink;
-    onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
-};

package/lib/versions/index.d.ts

@@ -38,3 +38,4 @@ export declare function readVersionsMetadata({ context, options, }: {
     options: PluginOptions;
 }): Promise<VersionMetadata[]>;
 export declare function toFullVersion(version: LoadedVersion): FullVersion;
+export declare function getVersionFromSourceFilePath(filePath: string, versionsMetadata: VersionMetadata[]): VersionMetadata;

package/lib/versions/index.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+exports.getVersionFromSourceFilePath = exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -171,3 +171,11 @@ function toFullVersion(version) {
     };
 }
 exports.toFullVersion = toFullVersion;
+function getVersionFromSourceFilePath(filePath, versionsMetadata) {
+    const versionFound = versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
+    if (!versionFound) {
+        throw new Error(`Unexpected error: file at "${filePath}" does not belong to any docs version!`);
+    }
+    return versionFound;
+}
+exports.getVersionFromSourceFilePath = getVersionFromSourceFilePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.3.2",
-    "@docusaurus/logger": "3.3.2",
-    "@docusaurus/mdx-loader": "3.3.2",
-    "@docusaurus/module-type-aliases": "3.3.2",
-    "@docusaurus/types": "3.3.2",
-    "@docusaurus/utils": "3.3.2",
-    "@docusaurus/utils-common": "3.3.2",
-    "@docusaurus/utils-validation": "3.3.2",
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/logger": "3.4.0",
+    "@docusaurus/mdx-loader": "3.4.0",
+    "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/types": "3.4.0",
+    "@docusaurus/utils": "3.4.0",
+    "@docusaurus/utils-common": "3.4.0",
+    "@docusaurus/utils-validation": "3.4.0",
     "@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": "bc638d674bfbde1e254ef306697f47e764b5e107"
+  "gitHead": "49e9a2143274a8dd795659b417b470bc42abbd6e"
 }

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

@@ -17,8 +17,15 @@ import {
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
   createSlugger,
+  resolveMarkdownLinkPathname,
   DEFAULT_PLUGIN_ID,
+  type SourceToPermalink,
+  type TagsFile,
 } from '@docusaurus/utils';
+import {
+  getTagsFile,
+  getTagsFilePathsToWatch,
+} from '@docusaurus/utils-validation';
 import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
 import {
@@ -28,7 +35,11 @@ import {
   type DocEnv,
   createDocsByIdIndex,
 } from './docs';
-import {readVersionsMetadata, toFullVersion} from './versions';
+import {
+  getVersionFromSourceFilePath,
+  readVersionsMetadata,
+  toFullVersion,
+} from './versions';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
@@ -38,6 +49,7 @@ import {
 } from './translations';
 import {createAllRoutes} from './routes';
 import {createSidebarsUtils} from './sidebars/utils';
+import type {Options as MDXLoaderOptions} from '@docusaurus/mdx-loader';
 
 import type {
   PluginOptions,
@@ -48,13 +60,31 @@ import type {
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext, Plugin} from '@docusaurus/types';
-import type {
-  SourceToPermalink,
-  DocFile,
-  DocsMarkdownOption,
-  FullVersion,
-} from './types';
-import type {RuleSetRule} from 'webpack';
+import type {DocFile, FullVersion} from './types';
+import type {RuleSetUseItem} from 'webpack';
+
+// 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: LoadedContent): SourceToPermalink {
+    const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+    return new Map(allDocs.map(({source, permalink}) => [source, permalink]));
+  }
+
+  // Mutable map update :/
+  function update(content: LoadedContent): void {
+    sourceToPermalink.clear();
+    computeSourceToPermalink(content).forEach((value, key) => {
+      sourceToPermalink.set(key, value);
+    });
+  }
+
+  return {get: () => sourceToPermalink, update};
+}
 
 export default async function pluginContentDocs(
   context: LoadContext,
@@ -82,6 +112,8 @@ export default async function pluginContentDocs(
   // TODO env should be injected into all plugins
   const env = process.env.NODE_ENV as DocEnv;
 
+  const sourceToPermalinkHelper = createSourceToPermalinkHelper();
+
   return {
     name: 'docusaurus-plugin-content-docs',
 
@@ -118,6 +150,10 @@ export default async function pluginContentDocs(
               (docsDirPath) => `${docsDirPath}/${pattern}`,
             ),
           ),
+          ...getTagsFilePathsToWatch({
+            contentPaths: version,
+            tags: options.tags,
+          }),
           `${version.contentPath}/**/${CategoryMetadataFilenamePattern}`,
         ];
         if (typeof version.sidebarFilePath === 'string') {
@@ -132,6 +168,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) {
@@ -151,6 +188,7 @@ export default async function pluginContentDocs(
             context,
             options,
             env,
+            tagsFile,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -159,8 +197,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
@@ -226,6 +270,8 @@ export default async function pluginContentDocs(
     },
 
     async contentLoaded({content, actions}) {
+      sourceToPermalinkHelper.update(content);
+
       const versions: FullVersion[] = content.loadedVersions.map(toFullVersion);
 
       await createAllRoutes({
@@ -251,72 +297,61 @@ export default async function pluginContentDocs(
         beforeDefaultRemarkPlugins,
       } = options;
 
-      function getSourceToPermalink(): SourceToPermalink {
-        const allDocs = content.loadedVersions.flatMap((v) => v.docs);
-        return Object.fromEntries(
-          allDocs.map(({source, permalink}) => [source, permalink]),
-        );
-      }
-
-      const docsMarkdownOptions: DocsMarkdownOption = {
-        siteDir,
-        sourceToPermalink: getSourceToPermalink(),
-        versionsMetadata,
-        onBrokenMarkdownLink: (brokenMarkdownLink) => {
-          logger.report(
-            siteConfig.onBrokenMarkdownLinks,
-          )`Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
-        },
-      };
+      const contentDirs = versionsMetadata
+        .flatMap(getContentPathList)
+        // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+        .map(addTrailingPathSeparator);
+
+      function createMDXLoader(): RuleSetUseItem {
+        const loaderOptions: MDXLoaderOptions = {
+          admonitions: options.admonitions,
+          remarkPlugins,
+          rehypePlugins,
+          beforeDefaultRehypePlugins,
+          beforeDefaultRemarkPlugins,
+          staticDirs: siteConfig.staticDirectories.map((dir) =>
+            path.resolve(siteDir, dir),
+          ),
+          siteDir,
+          isMDXPartial: createAbsoluteFilePathMatcher(
+            options.exclude,
+            contentDirs,
+          ),
+          metadataPath: (mdxPath: string) => {
+            // Note that metadataPath must be the same/in-sync as
+            // the path from createData for each MDX.
+            const aliasedPath = aliasedSitePath(mdxPath, siteDir);
+            return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
+          },
+          // Assets allow to convert some relative images paths to
+          // require(...) calls
+          createAssets: ({frontMatter}: {frontMatter: DocFrontMatter}) => ({
+            image: frontMatter.image,
+          }),
+          markdownConfig: siteConfig.markdown,
+          resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
+            const version = getVersionFromSourceFilePath(
+              sourceFilePath,
+              content.loadedVersions,
+            );
+            const permalink = resolveMarkdownLinkPathname(linkPathname, {
+              sourceFilePath,
+              sourceToPermalink: sourceToPermalinkHelper.get(),
+              siteDir,
+              contentPaths: version,
+            });
+            if (permalink === null) {
+              logger.report(
+                siteConfig.onBrokenMarkdownLinks,
+              )`Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
+            }
+            return permalink;
+          },
+        };
 
-      function createMDXLoaderRule(): RuleSetRule {
-        const contentDirs = versionsMetadata
-          .flatMap(getContentPathList)
-          // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
-          .map(addTrailingPathSeparator);
         return {
-          test: /\.mdx?$/i,
-          include: contentDirs,
-          use: [
-            {
-              loader: require.resolve('@docusaurus/mdx-loader'),
-              options: {
-                admonitions: options.admonitions,
-                remarkPlugins,
-                rehypePlugins,
-                beforeDefaultRehypePlugins,
-                beforeDefaultRemarkPlugins,
-                staticDirs: siteConfig.staticDirectories.map((dir) =>
-                  path.resolve(siteDir, dir),
-                ),
-                siteDir,
-                isMDXPartial: createAbsoluteFilePathMatcher(
-                  options.exclude,
-                  contentDirs,
-                ),
-                metadataPath: (mdxPath: string) => {
-                  // Note that metadataPath must be the same/in-sync as
-                  // the path from createData for each MDX.
-                  const aliasedPath = aliasedSitePath(mdxPath, siteDir);
-                  return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
-                },
-                // Assets allow to convert some relative images paths to
-                // require(...) calls
-                createAssets: ({
-                  frontMatter,
-                }: {
-                  frontMatter: DocFrontMatter;
-                }) => ({
-                  image: frontMatter.image,
-                }),
-                markdownConfig: siteConfig.markdown,
-              },
-            },
-            {
-              loader: path.resolve(__dirname, './markdown/index.js'),
-              options: docsMarkdownOptions,
-            },
-          ].filter(Boolean),
+          loader: require.resolve('@docusaurus/mdx-loader'),
+          options: loaderOptions,
         };
       }
 
@@ -333,7 +368,13 @@ export default async function pluginContentDocs(
           },
         },
         module: {
-          rules: [createMDXLoaderRule()],
+          rules: [
+            {
+              test: /\.mdx?$/i,
+              include: contentDirs,
+              use: [createMDXLoader()],
+            },
+          ],
         },
       };
     },

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,9 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
+import type {TagMetadata} from '@docusaurus/utils';
 import type {
-  VersionMetadata,
   LoadedVersion,
   CategoryGeneratedIndexMetadata,
 } from '@docusaurus/plugin-content-docs';
@@ -20,11 +19,7 @@ export type DocFile = {
   content: string;
 };
 
-export type SourceToPermalink = {
-  [source: string]: string;
-};
-
-export type VersionTag = Tag & {
+export type VersionTag = TagMetadata & {
   /** All doc ids having this tag. */
   docIds: string[];
   unlisted: boolean;
@@ -37,12 +32,3 @@ export type FullVersion = LoadedVersion & {
   sidebarsUtils: SidebarsUtils;
   categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-
-export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-
-export type DocsMarkdownOption = {
-  versionsMetadata: VersionMetadata[];
-  siteDir: string;
-  sourceToPermalink: SourceToPermalink;
-  onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
-};

package/src/versions/index.ts

@@ -6,7 +6,7 @@
  */
 
 import path from 'path';
-import {normalizeUrl, posixPath} from '@docusaurus/utils';
+import {getContentPathList, normalizeUrl, posixPath} from '@docusaurus/utils';
 import {CURRENT_VERSION_NAME} from '../constants';
 import {validateVersionsOptions} from './validation';
 import {
@@ -268,3 +268,20 @@ export function toFullVersion(version: LoadedVersion): FullVersion {
     }),
   };
 }
+
+export function getVersionFromSourceFilePath(
+  filePath: string,
+  versionsMetadata: VersionMetadata[],
+): VersionMetadata {
+  const versionFound = versionsMetadata.find((version) =>
+    getContentPathList(version).some((docsDirPath) =>
+      filePath.startsWith(docsDirPath),
+    ),
+  );
+  if (!versionFound) {
+    throw new Error(
+      `Unexpected error: file at "${filePath}" does not belong to any docs version!`,
+    );
+  }
+  return versionFound;
+}

package/lib/markdown/index.d.ts

@@ -1,9 +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 type { DocsMarkdownOption } from '../types';
-import type { LoaderContext } from 'webpack';
-export default function markdownLoader(this: LoaderContext<DocsMarkdownOption>, source: string): void;

package/lib/markdown/index.js

@@ -1,16 +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 });
-const linkify_1 = require("./linkify");
-function markdownLoader(source) {
-    const fileString = source;
-    const callback = this.async();
-    const options = this.getOptions();
-    return callback(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options));
-}
-exports.default = markdownLoader;

package/lib/markdown/linkify.d.ts

@@ -1,8 +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 type { DocsMarkdownOption } from '../types';
-export declare function linkify(fileString: string, filePath: string, options: DocsMarkdownOption): string;

package/lib/markdown/linkify.js

@@ -1,34 +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.linkify = void 0;
-const utils_1 = require("@docusaurus/utils");
-function getVersion(filePath, options) {
-    const versionFound = options.versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
-    // At this point, this should never happen, because the MDX loaders' paths are
-    // literally using the version content paths; but if we allow sourcing content
-    // from outside the docs directory (through the `include` option, for example;
-    // is there a compelling use-case?), this would actually be testable
-    if (!versionFound) {
-        throw new Error(`Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`);
-    }
-    return versionFound;
-}
-function linkify(fileString, filePath, options) {
-    const { siteDir, sourceToPermalink, onBrokenMarkdownLink } = options;
-    const { newContent, brokenMarkdownLinks } = (0, utils_1.replaceMarkdownLinks)({
-        siteDir,
-        fileString,
-        filePath,
-        contentPaths: getVersion(filePath, options),
-        sourceToPermalink,
-    });
-    brokenMarkdownLinks.forEach((l) => onBrokenMarkdownLink(l));
-    return newContent;
-}
-exports.linkify = linkify;

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/markdown/index.ts

@@ -1,20 +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 {linkify} from './linkify';
-import type {DocsMarkdownOption} from '../types';
-import type {LoaderContext} from 'webpack';
-
-export default function markdownLoader(
-  this: LoaderContext<DocsMarkdownOption>,
-  source: string,
-): void {
-  const fileString = source;
-  const callback = this.async();
-  const options = this.getOptions();
-  return callback(null, linkify(fileString, this.resourcePath, options));
-}

package/src/markdown/linkify.ts

@@ -1,47 +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 {replaceMarkdownLinks, getContentPathList} from '@docusaurus/utils';
-import type {DocsMarkdownOption} from '../types';
-
-function getVersion(filePath: string, options: DocsMarkdownOption) {
-  const versionFound = options.versionsMetadata.find((version) =>
-    getContentPathList(version).some((docsDirPath) =>
-      filePath.startsWith(docsDirPath),
-    ),
-  );
-  // At this point, this should never happen, because the MDX loaders' paths are
-  // literally using the version content paths; but if we allow sourcing content
-  // from outside the docs directory (through the `include` option, for example;
-  // is there a compelling use-case?), this would actually be testable
-  if (!versionFound) {
-    throw new Error(
-      `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,
-    );
-  }
-  return versionFound;
-}
-
-export function linkify(
-  fileString: string,
-  filePath: string,
-  options: DocsMarkdownOption,
-): string {
-  const {siteDir, sourceToPermalink, onBrokenMarkdownLink} = options;
-
-  const {newContent, brokenMarkdownLinks} = replaceMarkdownLinks({
-    siteDir,
-    fileString,
-    filePath,
-    contentPaths: getVersion(filePath, options),
-    sourceToPermalink,
-  });
-
-  brokenMarkdownLinks.forEach((l) => onBrokenMarkdownLink(l));
-
-  return newContent;
-}

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,
-    };
-  });
-}