feat: make tags route path configurable (#5545)

packages/docusaurus-plugin-content-blog/src/__tests__/generateBlogFeed.test.ts

@@ -52,6 +52,7 @@ describe('blogFeed', () => {
           {
             path: 'invalid-blog-path',
             routeBasePath: 'blog',
+            tagsBasePath: 'tags',
             authorsMapPath: 'authors.yml',
             include: ['*.md', '*.mdx'],
             feedOptions: {
@@ -86,6 +87,7 @@ describe('blogFeed', () => {
           {
             path: 'blog',
             routeBasePath: 'blog',
+            tagsBasePath: 'tags',
             authorsMapPath: 'authors.yml',
             include: DEFAULT_OPTIONS.include,
             exclude: DEFAULT_OPTIONS.exclude,

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -183,7 +183,13 @@ async function processBlogSourceFile(
     siteDir,
     i18n,
   } = context;
-  const {routeBasePath, truncateMarker, showReadingTime, editUrl} = options;
+  const {
+    routeBasePath,
+    tagsBasePath: tagsRouteBasePath,
+    truncateMarker,
+    showReadingTime,
+    editUrl,
+  } = options;
 
   // Lookup in localized folder in priority
   const blogDirPath = await getFolderContainingFile(
@@ -267,7 +273,11 @@ async function processBlogSourceFile(
     return undefined;
   }
 
-  const tagsBasePath = normalizeUrl([baseUrl, options.routeBasePath, 'tags']); // make this configurable?
+  const tagsBasePath = normalizeUrl([
+    baseUrl,
+    routeBasePath,
+    tagsRouteBasePath,
+  ]);
   const authors = getBlogPostAuthors({authorsMap, frontMatter});
 
   return {

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -124,6 +124,7 @@ export default function pluginContentBlog(
       const {
         postsPerPage: postsPerPageOption,
         routeBasePath,
+        tagsBasePath,
         blogDescription,
         blogTitle,
         blogSidebarTitle,
@@ -201,7 +202,7 @@ export default function pluginContentBlog(
 
       const blogTags: BlogTags = getBlogTags(blogPosts);
 
-      const tagsPath = normalizeUrl([baseBlogUrl, 'tags']);
+      const tagsPath = normalizeUrl([baseBlogUrl, tagsBasePath]);
 
       const blogTagsListPath =
         Object.keys(blogTags).length > 0 ? tagsPath : null;

packages/docusaurus-plugin-content-blog/src/pluginOptionSchema.ts

@@ -36,6 +36,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   include: ['**/*.{md,mdx}'],
   exclude: GlobExcludeDefault,
   routeBasePath: 'blog',
+  tagsBasePath: 'tags',
   archiveBasePath: 'archive',
   path: 'blog',
   editLocalizedFiles: false,
@@ -49,6 +50,7 @@ export const PluginOptionSchema = Joi.object<PluginOptions>({
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('')
     .default(DEFAULT_OPTIONS.routeBasePath),
+  tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   postsPerPage: Joi.alternatives()

packages/docusaurus-plugin-content-blog/src/types.ts

@@ -35,6 +35,7 @@ export interface PluginOptions extends RemarkAndRehypePluginOptions {
   id?: string;
   path: string;
   routeBasePath: string;
+  tagsBasePath: string;
   archiveBasePath: string;
   include: string[];
   exclude: string[];

packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts

@@ -40,6 +40,7 @@ describe('normalizeDocsPluginOptions', () => {
     const userOptions = {
       path: 'my-docs', // Path to data on filesystem, relative to site dir.
       routeBasePath: 'my-docs', // URL Route.
+      tagsBasePath: 'tags', // URL Tags Route.
       homePageId: 'home', // Document id for docs home page.
       include: ['**/*.{md,mdx}'], // Extensions to include.
       exclude: GlobExcludeDefault,

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -26,6 +26,7 @@ import {
 export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
   routeBasePath: 'docs', // URL Route.
+  tagsBasePath: 'tags', // URL Tags Route.
   homePageId: undefined, // TODO remove soon, deprecated
   include: ['**/*.{md,mdx}'], // Extensions to include.
   exclude: GlobExcludeDefault,
@@ -73,6 +74,7 @@ export const OptionsSchema = Joi.object({
     // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
     // .allow('') ""
     .default(DEFAULT_OPTIONS.routeBasePath),
+  tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath),
   homePageId: Joi.string().optional(),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -101,6 +101,7 @@ export type PluginOptions = MetadataOptions &
     disableVersioning: boolean;
     includeCurrentVersion: boolean;
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    tagsBasePath: string;
   };
 
 export type SidebarItemBase = {

packages/docusaurus-plugin-content-docs/src/versions.ts

@@ -349,6 +349,7 @@ function createVersionMetadata({
     | 'path'
     | 'sidebarPath'
     | 'routeBasePath'
+    | 'tagsBasePath'
     | 'versions'
     | 'editUrl'
     | 'editCurrentVersion'
@@ -400,7 +401,7 @@ function createVersionMetadata({
 
   // the path that will be used to refer the docs tags
   // example below will be using /docs/tags
-  const tagsPath = normalizeUrl([versionPath, 'tags']);
+  const tagsPath = normalizeUrl([versionPath, options.tagsBasePath]);
 
   return {
     versionName,
@@ -561,6 +562,7 @@ export function readVersionsMetadata({
     | 'path'
     | 'sidebarPath'
     | 'routeBasePath'
+    | 'tagsBasePath'
     | 'includeCurrentVersion'
     | 'disableVersioning'
     | 'lastVersion'

website/docs/api/plugins/plugin-content-blog.md

@@ -36,6 +36,7 @@ Accepted fields:
 | `blogSidebarCount` | <code>number \| 'ALL'</code> | `5` | Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable |
 | `blogSidebarTitle` | `string` | `'Recent posts'` | Title of the blog sidebar. |
 | `routeBasePath` | `string` | `'blog'` | URL route for the blog section of your site. **DO NOT** include a trailing slash. Use `/` to put the blog at root path. |
+| `tagsBasePath` | `string` | `'tags'` | URL route for the tags list page of your site. It is prepended to the `routeBasePath`. |
 | `archiveBasePath` | `string` | `'/archive'` | URL route for the archive blog section of your site. It is prepended to the `routeBasePath`. **DO NOT** include a trailing slash. |
 | `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
 | `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |

website/docs/api/plugins/plugin-content-docs.md

@@ -33,6 +33,7 @@ Accepted fields:
 | `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
 | `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. |
 | `routeBasePath` | `string` | `'docs'` | URL route for the docs section of your site. **DO NOT** include a trailing slash. Use `/` for shipping docs without base path. |
+| `tagsBasePath` | `string` | `'tags'` | URL route for the tags list page of your site. It is prepended to the `routeBasePath`. |
 | `include` | `string[]` | `['**/*.{md,mdx}']` | Matching files will be included and processed. |
 | `exclude` | `string[]` | _See example configuration_ | No route will be created for matching files. |
 | `sidebarPath` | <code>false \| string</code> | `undefined` (creates autogenerated sidebar) | Path to sidebar configuration. |