From 399e711660ff9ba1199e901c06347fab785fc078 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Sun, 21 Jan 2024 10:55:47 +0200 Subject: [PATCH 1/8] add pageBasePath to blog --- packages/docusaurus-plugin-content-blog/src/blogUtils.ts | 5 ++++- packages/docusaurus-plugin-content-blog/src/index.ts | 3 +++ packages/docusaurus-plugin-content-blog/src/options.ts | 2 ++ .../src/plugin-content-blog.d.ts | 5 +++++ 4 files changed, 14 insertions(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 3bbb5301bf92..74c66385f567 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -57,12 +57,14 @@ export function paginateBlogPosts({ blogTitle, blogDescription, postsPerPageOption, + pageBasePath, }: { blogPosts: BlogPost[]; basePageUrl: string; blogTitle: string; blogDescription: string; postsPerPageOption: number | 'ALL'; + pageBasePath: string; }): BlogPaginated[] { const totalCount = blogPosts.length; const postsPerPage = @@ -73,7 +75,7 @@ export function paginateBlogPosts({ function permalink(page: number) { return page > 0 - ? normalizeUrl([basePageUrl, `page/${page + 1}`]) + ? normalizeUrl([basePageUrl, `${pageBasePath}/${page + 1}`]) : basePageUrl; } @@ -111,6 +113,7 @@ export function getBlogTags({ blogTitle: string; blogDescription: string; postsPerPageOption: number | 'ALL'; + pageBasePath: string; }): BlogTags { const groups = groupTaggedItems( blogPosts, diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index 4605877ed75b..01f586797b88 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -107,6 +107,7 @@ export default async function pluginContentBlog( blogDescription, blogTitle, blogSidebarTitle, + pageBasePath, } = options; const baseBlogUrl = normalizeUrl([baseUrl, routeBasePath]); @@ -153,6 +154,7 @@ export default async function pluginContentBlog( blogDescription, postsPerPageOption, basePageUrl: baseBlogUrl, + pageBasePath, }); const blogTags: BlogTags = getBlogTags({ @@ -160,6 +162,7 @@ export default async function pluginContentBlog( postsPerPageOption, blogDescription, blogTitle, + pageBasePath, }); return { diff --git a/packages/docusaurus-plugin-content-blog/src/options.ts b/packages/docusaurus-plugin-content-blog/src/options.ts index 5b9889399a10..d1e6e9cc4547 100644 --- a/packages/docusaurus-plugin-content-blog/src/options.ts +++ b/packages/docusaurus-plugin-content-blog/src/options.ts @@ -45,6 +45,7 @@ export const DEFAULT_OPTIONS: PluginOptions = { routeBasePath: 'blog', tagsBasePath: 'tags', archiveBasePath: 'archive', + pageBasePath: 'page', path: 'blog', editLocalizedFiles: false, authorsMapPath: 'authors.yml', @@ -59,6 +60,7 @@ const PluginOptionSchema = Joi.object({ .allow(null), routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath), tagsBasePath: Joi.string().default(DEFAULT_OPTIONS.tagsBasePath), + pageBasePath: Joi.string().default(DEFAULT_OPTIONS.pageBasePath), include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include), exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude), postsPerPage: Joi.alternatives() diff --git a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts index b1915f75196f..4afdfc6a9c4b 100644 --- a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts +++ b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts @@ -354,6 +354,11 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the * `routeBasePath`. **DO NOT** include a trailing slash. */ tagsBasePath: string; + /** + * URL route for the pages section of your blog. Will be appended to + * `routeBasePath`. **DO NOT** include a trailing slash. + */ + pageBasePath: string; /** * URL route for the archive section of your blog. Will be appended to * `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to From 98d1fcbe54f8cbfd4eeea3d5d3db0f1c858da2e4 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 08:00:16 +0200 Subject: [PATCH 2/8] add website mentions of pageBasePath --- website/docs/advanced/routing.mdx | 1 + website/docs/api/plugins/plugin-content-blog.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/website/docs/advanced/routing.mdx b/website/docs/advanced/routing.mdx index e9e96d4892c7..7acc45ab6f98 100644 --- a/website/docs/advanced/routing.mdx +++ b/website/docs/advanced/routing.mdx @@ -53,6 +53,7 @@ The component used for Markdown pages is `@theme/MDXPage`. React pages are direc The blog creates the following routes: - **Posts list pages**: `/`, `/page/2`, `/page/3`... + - The route is customizable through the `pageBasePath` option. - The component is `@theme/BlogListPage`. - **Post pages**: `/2021/11/21/algolia-docsearch-migration`, `/2021/05/12/announcing-docusaurus-two-beta`... - Generated from each Markdown post. diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index 41a90b4058ab..ece8fed6a037 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/website/docs/api/plugins/plugin-content-blog.mdx @@ -48,6 +48,7 @@ Accepted fields: | `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 section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. | +| `pageBasePath` | `string` | `'page'` | URL route for the pages section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. | | `archiveBasePath` | string \| null | `'archive'` | URL route for the archive section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to disable generation of archive. | | `include` | `string[]` | `['**/*.{md,mdx}']` | Array of glob patterns matching Markdown files to be built, relative to the content path. | | `exclude` | `string[]` | _See example configuration_ | Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the `include` option. | From e143329e5d7ab807c1e13f09dad85885683ab525 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 14:18:35 +0200 Subject: [PATCH 3/8] fix blogUtils.test.ts --- .../src/__tests__/blogUtils.test.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts index 3ec0e9d9f90a..26f1315c4c77 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts @@ -53,6 +53,7 @@ describe('paginateBlogPosts', () => { blogTitle: 'Blog Title', blogDescription: 'Blog Description', postsPerPageOption: 2, + pageBasePath: 'page', }), ).toMatchSnapshot(); expect( @@ -62,6 +63,7 @@ describe('paginateBlogPosts', () => { blogTitle: 'Blog Title', blogDescription: 'Blog Description', postsPerPageOption: 2, + pageBasePath: 'page', }), ).toMatchSnapshot(); expect( @@ -71,6 +73,7 @@ describe('paginateBlogPosts', () => { blogTitle: 'Blog Title', blogDescription: 'Blog Description', postsPerPageOption: 10, + pageBasePath: 'page', }), ).toMatchSnapshot(); }); From a6e51983bd227cfd8ab0137f4bb71e69d6c7d09e Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 14:19:24 +0200 Subject: [PATCH 4/8] blogUtils.ts: improve normalize page permalink --- packages/docusaurus-plugin-content-blog/src/blogUtils.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 74c66385f567..e67e83345203 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -75,7 +75,7 @@ export function paginateBlogPosts({ function permalink(page: number) { return page > 0 - ? normalizeUrl([basePageUrl, `${pageBasePath}/${page + 1}`]) + ? normalizeUrl([basePageUrl, pageBasePath, `${page + 1}`]) : basePageUrl; } From 2e5408206839bb862be200ef191aab7a28bec9bb Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 14:19:58 +0200 Subject: [PATCH 5/8] remove blogTagsPaginated --- packages/docusaurus-plugin-content-blog/src/index.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index 01f586797b88..770a468f297a 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -122,11 +122,10 @@ export default async function pluginContentBlog( blogListPaginated: [], blogTags: {}, blogTagsListPath, - blogTagsPaginated: [], }; } - // Colocate next and prev metadata. + // Collocate next and prev metadata. listedBlogPosts.forEach((blogPost, index) => { const prevItem = index > 0 ? listedBlogPosts[index - 1] : null; if (prevItem) { From 056105cd36cc190b43fa268252971b10f42eee5c Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 14:20:32 +0200 Subject: [PATCH 6/8] remove **DO NOT** include a trailing slash --- .../src/plugin-content-blog.d.ts | 4 ++-- website/docs/api/plugins/plugin-content-blog.mdx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts index 4afdfc6a9c4b..7443e14e1621 100644 --- a/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts +++ b/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts @@ -351,12 +351,12 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the routeBasePath: string; /** * URL route for the tags section of your blog. Will be appended to - * `routeBasePath`. **DO NOT** include a trailing slash. + * `routeBasePath`. */ tagsBasePath: string; /** * URL route for the pages section of your blog. Will be appended to - * `routeBasePath`. **DO NOT** include a trailing slash. + * `routeBasePath`. */ pageBasePath: string; /** diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index ece8fed6a037..ec4332e5ff7b 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/website/docs/api/plugins/plugin-content-blog.mdx @@ -47,8 +47,8 @@ Accepted fields: | `blogSidebarCount` | number \| 'ALL' | `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 section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. | -| `pageBasePath` | `string` | `'page'` | URL route for the pages section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. | +| `tagsBasePath` | `string` | `'tags'` | URL route for the tags section of your blog. Will be appended to `routeBasePath`. | +| `pageBasePath` | `string` | `'page'` | URL route for the pages section of your blog. Will be appended to `routeBasePath`. | | `archiveBasePath` | string \| null | `'archive'` | URL route for the archive section of your blog. Will be appended to `routeBasePath`. **DO NOT** include a trailing slash. Use `null` to disable generation of archive. | | `include` | `string[]` | `['**/*.{md,mdx}']` | Array of glob patterns matching Markdown files to be built, relative to the content path. | | `exclude` | `string[]` | _See example configuration_ | Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the `include` option. | From 6c4c8a5a3ec26fa9bb8a7c6e3a564e0b2fe4d71a Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Fri, 9 Feb 2024 17:55:48 +0200 Subject: [PATCH 7/8] blogUtils.test.ts update page url --- .../src/__tests__/blogUtils.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts index 26f1315c4c77..492c30348080 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts @@ -73,7 +73,7 @@ describe('paginateBlogPosts', () => { blogTitle: 'Blog Title', blogDescription: 'Blog Description', postsPerPageOption: 10, - pageBasePath: 'page', + pageBasePath: 'a-page', }), ).toMatchSnapshot(); }); From dd81393529b66059323f4cad21dba0a878e1d315 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Feb 2024 19:43:57 +0100 Subject: [PATCH 8/8] refactor tests + add snapshot for pageBasePath param --- .../__snapshots__/blogUtils.test.ts.snap | 71 ++++++++++++++++--- .../src/__tests__/blogUtils.test.ts | 38 +++++++--- 2 files changed, 92 insertions(+), 17 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap index 6137538dad52..b8ae6939f72d 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/__snapshots__/blogUtils.test.ts.snap @@ -23,7 +23,32 @@ title: This post links to another one! [Linked post](/blog/2018/12/14/Happy-First-Birthday-Slash)" `; -exports[`paginateBlogPosts generates right pages 1`] = ` +exports[`paginateBlogPosts generates a single page 1`] = ` +[ + { + "items": [ + "post1", + "post2", + "post3", + "post4", + "post5", + ], + "metadata": { + "blogDescription": "Blog Description", + "blogTitle": "Blog Title", + "nextPage": undefined, + "page": 1, + "permalink": "/", + "postsPerPage": 10, + "previousPage": undefined, + "totalCount": 5, + "totalPages": 1, + }, + }, +] +`; + +exports[`paginateBlogPosts generates pages 1`] = ` [ { "items": [ @@ -78,7 +103,7 @@ exports[`paginateBlogPosts generates right pages 1`] = ` ] `; -exports[`paginateBlogPosts generates right pages 2`] = ` +exports[`paginateBlogPosts generates pages at blog root 1`] = ` [ { "items": [ @@ -133,26 +158,56 @@ exports[`paginateBlogPosts generates right pages 2`] = ` ] `; -exports[`paginateBlogPosts generates right pages 3`] = ` +exports[`paginateBlogPosts generates pages with custom pageBasePath 1`] = ` [ { "items": [ "post1", "post2", + ], + "metadata": { + "blogDescription": "Blog Description", + "blogTitle": "Blog Title", + "nextPage": "/blog/customPageBasePath/2", + "page": 1, + "permalink": "/blog", + "postsPerPage": 2, + "previousPage": undefined, + "totalCount": 5, + "totalPages": 3, + }, + }, + { + "items": [ "post3", "post4", + ], + "metadata": { + "blogDescription": "Blog Description", + "blogTitle": "Blog Title", + "nextPage": "/blog/customPageBasePath/3", + "page": 2, + "permalink": "/blog/customPageBasePath/2", + "postsPerPage": 2, + "previousPage": "/blog", + "totalCount": 5, + "totalPages": 3, + }, + }, + { + "items": [ "post5", ], "metadata": { "blogDescription": "Blog Description", "blogTitle": "Blog Title", "nextPage": undefined, - "page": 1, - "permalink": "/", - "postsPerPage": 10, - "previousPage": undefined, + "page": 3, + "permalink": "/blog/customPageBasePath/3", + "postsPerPage": 2, + "previousPage": "/blog/customPageBasePath/2", "totalCount": 5, - "totalPages": 1, + "totalPages": 3, }, }, ] diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts index 492c30348080..d96f1228c897 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts @@ -38,14 +38,15 @@ describe('truncate', () => { }); describe('paginateBlogPosts', () => { - it('generates right pages', () => { - const blogPosts = [ - {id: 'post1', metadata: {}, content: 'Foo 1'}, - {id: 'post2', metadata: {}, content: 'Foo 2'}, - {id: 'post3', metadata: {}, content: 'Foo 3'}, - {id: 'post4', metadata: {}, content: 'Foo 4'}, - {id: 'post5', metadata: {}, content: 'Foo 5'}, - ] as BlogPost[]; + const blogPosts = [ + {id: 'post1', metadata: {}, content: 'Foo 1'}, + {id: 'post2', metadata: {}, content: 'Foo 2'}, + {id: 'post3', metadata: {}, content: 'Foo 3'}, + {id: 'post4', metadata: {}, content: 'Foo 4'}, + {id: 'post5', metadata: {}, content: 'Foo 5'}, + ] as BlogPost[]; + + it('generates pages', () => { expect( paginateBlogPosts({ blogPosts, @@ -56,6 +57,9 @@ describe('paginateBlogPosts', () => { pageBasePath: 'page', }), ).toMatchSnapshot(); + }); + + it('generates pages at blog root', () => { expect( paginateBlogPosts({ blogPosts, @@ -66,6 +70,9 @@ describe('paginateBlogPosts', () => { pageBasePath: 'page', }), ).toMatchSnapshot(); + }); + + it('generates a single page', () => { expect( paginateBlogPosts({ blogPosts, @@ -73,7 +80,20 @@ describe('paginateBlogPosts', () => { blogTitle: 'Blog Title', blogDescription: 'Blog Description', postsPerPageOption: 10, - pageBasePath: 'a-page', + pageBasePath: 'page', + }), + ).toMatchSnapshot(); + }); + + it('generates pages with custom pageBasePath', () => { + expect( + paginateBlogPosts({ + blogPosts, + basePageUrl: '/blog', + blogTitle: 'Blog Title', + blogDescription: 'Blog Description', + postsPerPageOption: 2, + pageBasePath: 'customPageBasePath', }), ).toMatchSnapshot(); });