@docusaurus/utils 0.0.0-5957 → 0.0.0-5962

package/lib/index.d.ts

@@ -11,7 +11,7 @@ export { mergeTranslations, updateTranslationFileMessages, getPluginI18nPath, lo
 export { mapAsyncSequential, findAsyncSequential } from './jsUtils';
 export { normalizeUrl, getEditUrl, fileToPath, encodePath, isValidPathname, resolvePathname, parseURLPath, parseLocalURLPath, parseURLOrPath, toURLPath, serializeURLPath, hasSSHProtocol, buildHttpsUrl, buildSshUrl, } from './urlUtils';
 export type { URLPath } from './urlUtils';
-export { type Tag, type TagsListItem, type TagModule, type FrontMatterTag, normalizeFrontMatterTags, groupTaggedItems, getTagVisibility, } from './tags';
+export { type Tag, type TagsFile, type TagsFileInput, type TagMetadata, type TagsListItem, type TagModule, type FrontMatterTag, type TagsPluginOptions, groupTaggedItems, getTagVisibility, } from './tags';
 export { parseMarkdownHeadingId, escapeMarkdownHeadingIds, unwrapMdxCodeBlocks, admonitionTitleToDirectiveLabel, createExcerpt, DEFAULT_PARSE_FRONT_MATTER, parseMarkdownContentTitle, parseMarkdownFile, writeMarkdownHeadingId, type WriteHeadingIDOptions, } from './markdownUtils';
 export { type ContentPaths, resolveMarkdownLinkPathname } from './markdownLinks';
 export { type SluggerOptions, type Slugger, createSlugger } from './slugger';
@@ -27,4 +27,5 @@ export { escapeRegexp } from './regExpUtils';
 export { askPreferredLanguage } from './cliUtils';
 export { flattenRoutes } from './routeUtils';
 export { getGitLastUpdate, getLastUpdate, readLastUpdateData, LAST_UPDATE_FALLBACK, type LastUpdateData, type FrontMatterLastUpdate, } from './lastUpdateUtils';
+export { normalizeTags, reportInlineTags } from './tags';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,EACZ,uBAAuB,EACvB,6BAA6B,EAC7B,UAAU,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,QAAQ,EAAE,kBAAkB,EAAC,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,kBAAkB,EAAE,mBAAmB,EAAC,MAAM,WAAW,CAAC;AAClE,OAAO,EACL,YAAY,EACZ,UAAU,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAC,OAAO,EAAC,MAAM,YAAY,CAAC;AACxC,OAAO,EACL,KAAK,GAAG,EACR,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,EAC/B,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAC,KAAK,YAAY,EAAE,2BAA2B,EAAC,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAC,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,aAAa,EAAC,MAAM,WAAW,CAAC;AAC3E,OAAO,EACL,aAAa,EACb,SAAS,EACT,SAAS,EACT,yBAAyB,EACzB,eAAe,EACf,6BAA6B,EAC7B,UAAU,EACV,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAC,MAAM,aAAa,CAAC;AAC1D,OAAO,EACL,MAAM,EACN,kBAAkB,EAClB,aAAa,EACb,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAC,cAAc,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAC9C,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAC,OAAO,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAC,oBAAoB,EAAC,MAAM,YAAY,CAAC;AAChD,OAAO,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -6,8 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PARSE_FRONT_MATTER = exports.createExcerpt = exports.admonitionTitleToDirectiveLabel = exports.unwrapMdxCodeBlocks = exports.escapeMarkdownHeadingIds = exports.parseMarkdownHeadingId = exports.getTagVisibility = exports.groupTaggedItems = exports.normalizeFrontMatterTags = exports.buildSshUrl = exports.buildHttpsUrl = exports.hasSSHProtocol = exports.serializeURLPath = exports.toURLPath = exports.parseURLOrPath = exports.parseLocalURLPath = exports.parseURLPath = exports.resolvePathname = exports.isValidPathname = exports.encodePath = exports.fileToPath = exports.getEditUrl = exports.normalizeUrl = exports.findAsyncSequential = exports.mapAsyncSequential = exports.localizePath = exports.getPluginI18nPath = exports.updateTranslationFileMessages = exports.mergeTranslations = exports.GitNotFoundError = exports.FileNotTrackedError = exports.getFileCommitDate = exports.readOutputHTMLFile = exports.generate = exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.CODE_TRANSLATIONS_FILE_NAME = exports.DEFAULT_I18N_DIR_NAME = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.DEFAULT_STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.DOCUSAURUS_VERSION = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
-exports.LAST_UPDATE_FALLBACK = exports.readLastUpdateData = exports.getLastUpdate = exports.getGitLastUpdate = exports.flattenRoutes = exports.askPreferredLanguage = exports.escapeRegexp = exports.isUnlisted = exports.isDraft = exports.getFolderContainingFile = exports.findFolderContainingFile = exports.getContentPathList = exports.getDataFileData = exports.getDataFilePath = exports.loadFreshModule = exports.escapeShellArg = exports.getWebpackLoaderCompilerName = exports.getFileLoaderUtils = exports.createAbsoluteFilePathMatcher = exports.createMatcher = exports.GlobExcludeDefault = exports.Globby = exports.docuHash = exports.simpleHash = exports.md5Hash = exports.addTrailingPathSeparator = exports.escapePath = exports.aliasedSitePathToRelativePath = exports.aliasedSitePath = exports.toMessageRelativeFilePath = exports.posixPath = exports.shortName = exports.isNameTooLong = exports.createSlugger = exports.resolveMarkdownLinkPathname = exports.writeMarkdownHeadingId = exports.parseMarkdownFile = exports.parseMarkdownContentTitle = void 0;
+exports.parseMarkdownContentTitle = exports.DEFAULT_PARSE_FRONT_MATTER = exports.createExcerpt = exports.admonitionTitleToDirectiveLabel = exports.unwrapMdxCodeBlocks = exports.escapeMarkdownHeadingIds = exports.parseMarkdownHeadingId = exports.getTagVisibility = exports.groupTaggedItems = exports.buildSshUrl = exports.buildHttpsUrl = exports.hasSSHProtocol = exports.serializeURLPath = exports.toURLPath = exports.parseURLOrPath = exports.parseLocalURLPath = exports.parseURLPath = exports.resolvePathname = exports.isValidPathname = exports.encodePath = exports.fileToPath = exports.getEditUrl = exports.normalizeUrl = exports.findAsyncSequential = exports.mapAsyncSequential = exports.localizePath = exports.getPluginI18nPath = exports.updateTranslationFileMessages = exports.mergeTranslations = exports.GitNotFoundError = exports.FileNotTrackedError = exports.getFileCommitDate = exports.readOutputHTMLFile = exports.generate = exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.CODE_TRANSLATIONS_FILE_NAME = exports.DEFAULT_I18N_DIR_NAME = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.DEFAULT_STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.DOCUSAURUS_VERSION = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
+exports.reportInlineTags = exports.normalizeTags = exports.LAST_UPDATE_FALLBACK = exports.readLastUpdateData = exports.getLastUpdate = exports.getGitLastUpdate = exports.flattenRoutes = exports.askPreferredLanguage = exports.escapeRegexp = exports.isUnlisted = exports.isDraft = exports.getFolderContainingFile = exports.findFolderContainingFile = exports.getContentPathList = exports.getDataFileData = exports.getDataFilePath = exports.loadFreshModule = exports.escapeShellArg = exports.getWebpackLoaderCompilerName = exports.getFileLoaderUtils = exports.createAbsoluteFilePathMatcher = exports.createMatcher = exports.GlobExcludeDefault = exports.Globby = exports.docuHash = exports.simpleHash = exports.md5Hash = exports.addTrailingPathSeparator = exports.escapePath = exports.aliasedSitePathToRelativePath = exports.aliasedSitePath = exports.toMessageRelativeFilePath = exports.posixPath = exports.shortName = exports.isNameTooLong = exports.createSlugger = exports.resolveMarkdownLinkPathname = exports.writeMarkdownHeadingId = exports.parseMarkdownFile = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "NODE_MAJOR_VERSION", { enumerable: true, get: function () { return constants_1.NODE_MAJOR_VERSION; } });
 Object.defineProperty(exports, "NODE_MINOR_VERSION", { enumerable: true, get: function () { return constants_1.NODE_MINOR_VERSION; } });
@@ -56,7 +56,6 @@ Object.defineProperty(exports, "hasSSHProtocol", { enumerable: true, get: functi
 Object.defineProperty(exports, "buildHttpsUrl", { enumerable: true, get: function () { return urlUtils_1.buildHttpsUrl; } });
 Object.defineProperty(exports, "buildSshUrl", { enumerable: true, get: function () { return urlUtils_1.buildSshUrl; } });
 var tags_1 = require("./tags");
-Object.defineProperty(exports, "normalizeFrontMatterTags", { enumerable: true, get: function () { return tags_1.normalizeFrontMatterTags; } });
 Object.defineProperty(exports, "groupTaggedItems", { enumerable: true, get: function () { return tags_1.groupTaggedItems; } });
 Object.defineProperty(exports, "getTagVisibility", { enumerable: true, get: function () { return tags_1.getTagVisibility; } });
 var markdownUtils_1 = require("./markdownUtils");
@@ -118,4 +117,7 @@ Object.defineProperty(exports, "getGitLastUpdate", { enumerable: true, get: func
 Object.defineProperty(exports, "getLastUpdate", { enumerable: true, get: function () { return lastUpdateUtils_1.getLastUpdate; } });
 Object.defineProperty(exports, "readLastUpdateData", { enumerable: true, get: function () { return lastUpdateUtils_1.readLastUpdateData; } });
 Object.defineProperty(exports, "LAST_UPDATE_FALLBACK", { enumerable: true, get: function () { return lastUpdateUtils_1.LAST_UPDATE_FALLBACK; } });
+var tags_2 = require("./tags");
+Object.defineProperty(exports, "normalizeTags", { enumerable: true, get: function () { return tags_2.normalizeTags; } });
+Object.defineProperty(exports, "reportInlineTags", { enumerable: true, get: function () { return tags_2.reportInlineTags; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/tags.d.ts

@@ -4,11 +4,25 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/** What the user configures. */
+import type { Optional } from 'utility-types';
 export type Tag = {
+    /** The display label of a tag */
     label: string;
     /** Permalink to this tag's page, without the `/tags/` base path. */
     permalink: string;
+    /** An optional description of the tag */
+    description: string | undefined;
+};
+export type TagsFileInput = Record<string, Partial<Tag> | null>;
+export type TagsFile = Record<string, Tag>;
+export type TagsPluginOptions = {
+    /** Path to the tags file. */
+    tags: string | false | null | undefined;
+    /** The behavior of Docusaurus when it found inline tags. */
+    onInlineTags: 'ignore' | 'log' | 'warn' | 'throw';
+};
+export type TagMetadata = Tag & {
+    inline: boolean;
 };
 /** What the tags list page should know about each tag. */
 export type TagsListItem = Tag & {
@@ -22,23 +36,26 @@ export type TagModule = TagsListItem & {
     /** Is this tag unlisted? (when it only contains unlisted items) */
     unlisted: boolean;
 };
-export type FrontMatterTag = string | Tag;
-/**
- * Takes tag objects as they are defined in front matter, and normalizes each
- * into a standard tag object. The permalink is created by appending the
- * sluggified label to `tagsPath`. Front matter tags already containing
- * permalinks would still have `tagsPath` prepended.
- *
- * The result will always be unique by permalinks. The behavior with colliding
- * permalinks is undetermined.
- */
-export declare function normalizeFrontMatterTags(
-/** Base path to append the tag permalinks to. */
-tagsPath: string, 
-/** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
-frontMatterTags?: FrontMatterTag[] | undefined): Tag[];
+export type FrontMatterTag = string | Optional<Tag, 'description'>;
+export declare function normalizeTag({ tag, tagsFile, tagsBaseRoutePath, }: {
+    tag: FrontMatterTag;
+    tagsBaseRoutePath: string;
+    tagsFile: TagsFile | null;
+}): TagMetadata;
+export declare function normalizeTags({ options, source, frontMatterTags, tagsBaseRoutePath, tagsFile, }: {
+    options: TagsPluginOptions;
+    source: string;
+    frontMatterTags: FrontMatterTag[] | undefined;
+    tagsBaseRoutePath: string;
+    tagsFile: TagsFile | null;
+}): TagMetadata[];
+export declare function reportInlineTags({ tags, source, options, }: {
+    tags: TagMetadata[];
+    source: string;
+    options: TagsPluginOptions;
+}): void;
 type TaggedItemGroup<Item> = {
-    tag: Tag;
+    tag: TagMetadata;
     items: Item[];
 };
 /**
@@ -54,7 +71,7 @@ export declare function groupTaggedItems<Item>(items: readonly Item[],
  * A callback telling me how to get the tags list of the current item. Usually
  * simply getting it from some metadata of the current item.
  */
-getItemTags: (item: Item) => readonly Tag[]): {
+getItemTags: (item: Item) => readonly TagMetadata[]): {
     [permalink: string]: TaggedItemGroup<Item>;
 };
 /**

package/lib/tags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,gCAAgC;AAChC,MAAM,MAAM,GAAG,GAAG;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG,GAAG,GAAG;IAC/B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG;IACrC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,GAAG,CAAC;AAgC1C;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB;AACtC,iDAAiD;AACjD,QAAQ,EAAE,MAAM;AAChB,8EAA8E;AAC9E,eAAe,GAAE,cAAc,EAAE,GAAG,SAAc,GACjD,GAAG,EAAE,CAMP;AAED,KAAK,eAAe,CAAC,IAAI,IAAI;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,KAAK,EAAE,IAAI,EAAE,CAAC;CACf,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EACnC,KAAK,EAAE,SAAS,IAAI,EAAE;AACtB;;;GAGG;AACH,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,GAAG,EAAE,GAC1C;IAAC,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;CAAC,CA0B9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,EACrC,KAAK,EACL,UAAU,GACX,EAAE;IACD,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC;CACrC,GAAG;IACF,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,IAAI,EAAE,CAAC;CACrB,CAaA"}
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"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"}

package/lib/tags.js

@@ -6,50 +6,79 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTagVisibility = exports.groupTaggedItems = exports.normalizeFrontMatterTags = void 0;
+exports.getTagVisibility = exports.groupTaggedItems = exports.reportInlineTags = exports.normalizeTags = exports.normalizeTag = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const urlUtils_1 = require("./urlUtils");
-function normalizeFrontMatterTag(tagsPath, frontMatterTag) {
+// We always apply tagsBaseRoutePath on purpose. For versioned docs, v1/doc.md
+// and v2/doc.md tags with custom permalinks don't lead to the same created
+// page. tagsBaseRoutePath is different for each doc version
+function normalizeTagPermalink({ tagsBaseRoutePath, permalink, }) {
+    return (0, urlUtils_1.normalizeUrl)([tagsBaseRoutePath, permalink]);
+}
+function normalizeInlineTag(tagsBaseRoutePath, frontMatterTag) {
     function toTagObject(tagString) {
         return {
+            inline: true,
             label: tagString,
             permalink: lodash_1.default.kebabCase(tagString),
+            description: undefined,
         };
     }
-    // TODO maybe make ensure the permalink is valid url path?
-    function normalizeTagPermalink(permalink) {
-        // Note: we always apply tagsPath on purpose. For versioned docs, v1/doc.md
-        // and v2/doc.md tags with custom permalinks don't lead to the same created
-        // page. tagsPath is different for each doc version
-        return (0, urlUtils_1.normalizeUrl)([tagsPath, permalink]);
-    }
     const tag = typeof frontMatterTag === 'string'
         ? toTagObject(frontMatterTag)
-        : frontMatterTag;
+        : { ...frontMatterTag, description: frontMatterTag.description };
     return {
+        inline: true,
         label: tag.label,
-        permalink: normalizeTagPermalink(tag.permalink),
+        permalink: normalizeTagPermalink({
+            permalink: tag.permalink,
+            tagsBaseRoutePath,
+        }),
+        description: tag.description,
     };
 }
-/**
- * Takes tag objects as they are defined in front matter, and normalizes each
- * into a standard tag object. The permalink is created by appending the
- * sluggified label to `tagsPath`. Front matter tags already containing
- * permalinks would still have `tagsPath` prepended.
- *
- * The result will always be unique by permalinks. The behavior with colliding
- * permalinks is undetermined.
- */
-function normalizeFrontMatterTags(
-/** Base path to append the tag permalinks to. */
-tagsPath, 
-/** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
-frontMatterTags = []) {
-    const tags = frontMatterTags.map((tag) => normalizeFrontMatterTag(tagsPath, tag));
-    return lodash_1.default.uniqBy(tags, (tag) => tag.permalink);
+function normalizeTag({ tag, tagsFile, tagsBaseRoutePath, }) {
+    if (typeof tag === 'string') {
+        const tagDescription = tagsFile?.[tag];
+        if (tagDescription) {
+            // pre-defined tag from tags.yml
+            return {
+                inline: false,
+                label: tagDescription.label,
+                permalink: normalizeTagPermalink({
+                    permalink: tagDescription.permalink,
+                    tagsBaseRoutePath,
+                }),
+                description: tagDescription.description,
+            };
+        }
+    }
+    // legacy inline tag object, always inline, unknown because isn't a string
+    return normalizeInlineTag(tagsBaseRoutePath, tag);
+}
+exports.normalizeTag = normalizeTag;
+function normalizeTags({ options, source, frontMatterTags, tagsBaseRoutePath, tagsFile, }) {
+    const tags = (frontMatterTags ?? []).map((tag) => normalizeTag({ tag, tagsBaseRoutePath, tagsFile }));
+    if (tagsFile !== null) {
+        reportInlineTags({ tags, source, options });
+    }
+    return tags;
+}
+exports.normalizeTags = normalizeTags;
+function reportInlineTags({ tags, source, options, }) {
+    if (options.onInlineTags === 'ignore') {
+        return;
+    }
+    const inlineTags = tags.filter((tag) => tag.inline);
+    if (inlineTags.length > 0) {
+        const uniqueUnknownTags = [...new Set(inlineTags.map((tag) => tag.label))];
+        const tagListString = uniqueUnknownTags.join(', ');
+        logger_1.default.report(options.onInlineTags)(`Tags [${tagListString}] used in ${source} are not defined in ${options.tags ?? 'tags.yml'}`);
+    }
 }
-exports.normalizeFrontMatterTags = normalizeFrontMatterTags;
+exports.reportInlineTags = reportInlineTags;
 /**
  * Permits to group docs/blog posts by tag (provided by front matter).
  *

package/lib/tags.js.map

@@ -1 +1 @@
-{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "0.0.0-5957",
+  "version": "0.0.0-5962",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,8 +18,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "0.0.0-5957",
-    "@docusaurus/utils-common": "0.0.0-5957",
+    "@docusaurus/logger": "0.0.0-5962",
+    "@docusaurus/utils-common": "0.0.0-5962",
     "@svgr/webpack": "^8.1.0",
     "escape-string-regexp": "^4.0.0",
     "file-loader": "^6.2.0",
@@ -36,13 +36,14 @@
     "shelljs": "^0.8.5",
     "tslib": "^2.6.0",
     "url-loader": "^4.1.1",
+    "utility-types": "^3.10.0",
     "webpack": "^5.88.1"
   },
   "engines": {
     "node": ">=18.0"
   },
   "devDependencies": {
-    "@docusaurus/types": "0.0.0-5957",
+    "@docusaurus/types": "0.0.0-5962",
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
@@ -58,5 +59,5 @@
       "optional": true
     }
   },
-  "gitHead": "edb3a453b0b3a853eadfc4e9ec44d47ea76d5002"
+  "gitHead": "35386a1d384d8e8757ef9f993b84dd5accc00e97"
 }

package/src/index.ts

@@ -55,10 +55,13 @@ export {
 export type {URLPath} from './urlUtils';
 export {
   type Tag,
+  type TagsFile,
+  type TagsFileInput,
+  type TagMetadata,
   type TagsListItem,
   type TagModule,
   type FrontMatterTag,
-  normalizeFrontMatterTags,
+  type TagsPluginOptions,
   groupTaggedItems,
   getTagVisibility,
 } from './tags';
@@ -120,3 +123,5 @@ export {
   type LastUpdateData,
   type FrontMatterLastUpdate,
 } from './lastUpdateUtils';
+
+export {normalizeTags, reportInlineTags} from './tags';

package/src/tags.ts

@@ -6,13 +6,34 @@
  */
 
 import _ from 'lodash';
+import logger from '@docusaurus/logger';
 import {normalizeUrl} from './urlUtils';
+import type {Optional} from 'utility-types';
 
-/** What the user configures. */
 export type Tag = {
+  /** The display label of a tag */
   label: string;
   /** Permalink to this tag's page, without the `/tags/` base path. */
   permalink: string;
+  /** An optional description of the tag */
+  description: string | undefined;
+};
+
+export type TagsFileInput = Record<string, Partial<Tag> | null>;
+
+export type TagsFile = Record<string, Tag>;
+
+// Tags plugins options shared between docs/blog
+export type TagsPluginOptions = {
+  // TODO allow option tags later? | TagsFile;
+  /** Path to the tags file. */
+  tags: string | false | null | undefined;
+  /** The behavior of Docusaurus when it found inline tags. */
+  onInlineTags: 'ignore' | 'log' | 'warn' | 'throw';
+};
+
+export type TagMetadata = Tag & {
+  inline: boolean;
 };
 
 /** What the tags list page should know about each tag. */
@@ -29,62 +50,126 @@ export type TagModule = TagsListItem & {
   unlisted: boolean;
 };
 
-export type FrontMatterTag = string | Tag;
+export type FrontMatterTag = string | Optional<Tag, 'description'>;
 
-function normalizeFrontMatterTag(
-  tagsPath: string,
+// We always apply tagsBaseRoutePath on purpose. For versioned docs, v1/doc.md
+// and v2/doc.md tags with custom permalinks don't lead to the same created
+// page. tagsBaseRoutePath is different for each doc version
+function normalizeTagPermalink({
+  tagsBaseRoutePath,
+  permalink,
+}: {
+  tagsBaseRoutePath: string;
+  permalink: string;
+}): string {
+  return normalizeUrl([tagsBaseRoutePath, permalink]);
+}
+
+function normalizeInlineTag(
+  tagsBaseRoutePath: string,
   frontMatterTag: FrontMatterTag,
-): Tag {
-  function toTagObject(tagString: string): Tag {
+): TagMetadata {
+  function toTagObject(tagString: string): TagMetadata {
     return {
+      inline: true,
       label: tagString,
       permalink: _.kebabCase(tagString),
+      description: undefined,
     };
   }
 
-  // TODO maybe make ensure the permalink is valid url path?
-  function normalizeTagPermalink(permalink: string): string {
-    // Note: we always apply tagsPath on purpose. For versioned docs, v1/doc.md
-    // and v2/doc.md tags with custom permalinks don't lead to the same created
-    // page. tagsPath is different for each doc version
-    return normalizeUrl([tagsPath, permalink]);
-  }
-
   const tag: Tag =
     typeof frontMatterTag === 'string'
       ? toTagObject(frontMatterTag)
-      : frontMatterTag;
+      : {...frontMatterTag, description: frontMatterTag.description};
 
   return {
+    inline: true,
     label: tag.label,
-    permalink: normalizeTagPermalink(tag.permalink),
+    permalink: normalizeTagPermalink({
+      permalink: tag.permalink,
+      tagsBaseRoutePath,
+    }),
+    description: tag.description,
   };
 }
 
-/**
- * Takes tag objects as they are defined in front matter, and normalizes each
- * into a standard tag object. The permalink is created by appending the
- * sluggified label to `tagsPath`. Front matter tags already containing
- * permalinks would still have `tagsPath` prepended.
- *
- * The result will always be unique by permalinks. The behavior with colliding
- * permalinks is undetermined.
- */
-export function normalizeFrontMatterTags(
-  /** Base path to append the tag permalinks to. */
-  tagsPath: string,
-  /** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
-  frontMatterTags: FrontMatterTag[] | undefined = [],
-): Tag[] {
-  const tags = frontMatterTags.map((tag) =>
-    normalizeFrontMatterTag(tagsPath, tag),
+export function normalizeTag({
+  tag,
+  tagsFile,
+  tagsBaseRoutePath,
+}: {
+  tag: FrontMatterTag;
+  tagsBaseRoutePath: string;
+  tagsFile: TagsFile | null;
+}): TagMetadata {
+  if (typeof tag === 'string') {
+    const tagDescription = tagsFile?.[tag];
+    if (tagDescription) {
+      // pre-defined tag from tags.yml
+      return {
+        inline: false,
+        label: tagDescription.label,
+        permalink: normalizeTagPermalink({
+          permalink: tagDescription.permalink,
+          tagsBaseRoutePath,
+        }),
+        description: tagDescription.description,
+      };
+    }
+  }
+  // legacy inline tag object, always inline, unknown because isn't a string
+  return normalizeInlineTag(tagsBaseRoutePath, tag);
+}
+
+export function normalizeTags({
+  options,
+  source,
+  frontMatterTags,
+  tagsBaseRoutePath,
+  tagsFile,
+}: {
+  options: TagsPluginOptions;
+  source: string;
+  frontMatterTags: FrontMatterTag[] | undefined;
+  tagsBaseRoutePath: string;
+  tagsFile: TagsFile | null;
+}): TagMetadata[] {
+  const tags = (frontMatterTags ?? []).map((tag) =>
+    normalizeTag({tag, tagsBaseRoutePath, tagsFile}),
   );
+  if (tagsFile !== null) {
+    reportInlineTags({tags, source, options});
+  }
+  return tags;
+}
 
-  return _.uniqBy(tags, (tag) => tag.permalink);
+export function reportInlineTags({
+  tags,
+  source,
+  options,
+}: {
+  tags: TagMetadata[];
+  source: string;
+  options: TagsPluginOptions;
+}): void {
+  if (options.onInlineTags === 'ignore') {
+    return;
+  }
+  const inlineTags = tags.filter((tag) => tag.inline);
+  if (inlineTags.length > 0) {
+    const uniqueUnknownTags = [...new Set(inlineTags.map((tag) => tag.label))];
+    const tagListString = uniqueUnknownTags.join(', ');
+    logger.report(options.onInlineTags)(
+      `Tags [${tagListString}] used in ${source} are not defined in ${
+        options.tags ?? 'tags.yml'
+      }`,
+    );
+  }
 }
 
 type TaggedItemGroup<Item> = {
-  tag: Tag;
+  tag: TagMetadata;
   items: Item[];
 };
 
@@ -102,7 +187,7 @@ export function groupTaggedItems<Item>(
    * A callback telling me how to get the tags list of the current item. Usually
    * simply getting it from some metadata of the current item.
    */
-  getItemTags: (item: Item) => readonly Tag[],
+  getItemTags: (item: Item) => readonly TagMetadata[],
 ): {[permalink: string]: TaggedItemGroup<Item>} {
   const result: {[permalink: string]: TaggedItemGroup<Item>} = {};