From bbb522d0af47a754ec2d1f24e793acdc0d97f93d Mon Sep 17 00:00:00 2001 From: ozakione <29860391+OzakIOne@users.noreply.github.com> Date: Mon, 5 Aug 2024 17:42:10 +0200 Subject: [PATCH 1/9] feat: onUntruncatedBlogPost blog options --- .../src/blogUtils.ts | 25 +++++++++++++++++++ .../src/options.ts | 4 +++ .../src/plugin-content-blog.d.ts | 1 + website/_dogfooding/dogfooding.config.ts | 1 + .../docs/api/plugins/plugin-content-blog.mdx | 1 + website/docusaurus.config.ts | 1 + 6 files changed, 33 insertions(+) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index d26d319c0f1b..d43202c744c1 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -47,6 +47,24 @@ export function truncate(fileString: string, truncateMarker: RegExp): string { return fileString.split(truncateMarker, 1).shift()!; } +function reportTruncateMarkerProblem({ + blogSourceRelative, + truncateMarker, + options, + content, +}: { + content: string; + truncateMarker: RegExp; + blogSourceRelative: string; + options: Pick; +}): void { + if (!truncateMarker.test(content)) { + logger.report(options.onUntruncatedBlogPost)( + logger.interpolate`Blog post path=${blogSourceRelative} is not truncated.`, + ); + } +} + export function paginateBlogPosts({ blogPosts, basePageUrl, @@ -228,6 +246,13 @@ async function processBlogSourceFile( parseFrontMatter, }); + reportTruncateMarkerProblem({ + blogSourceRelative, + truncateMarker, + options, + content, + }); + const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir); const lastUpdate = await readLastUpdateData( diff --git a/packages/docusaurus-plugin-content-blog/src/options.ts b/packages/docusaurus-plugin-content-blog/src/options.ts index e9d91d3bf449..9bf48f5fa00a 100644 --- a/packages/docusaurus-plugin-content-blog/src/options.ts +++ b/packages/docusaurus-plugin-content-blog/src/options.ts @@ -72,6 +72,7 @@ export const DEFAULT_OPTIONS: PluginOptions = { tags: undefined, authorsBasePath: 'authors', onInlineAuthors: 'warn', + onUntruncatedBlogPost: 'warn', }; export const XSLTBuiltInPaths = { @@ -240,6 +241,9 @@ const PluginOptionSchema = Joi.object({ onInlineAuthors: Joi.string() .equal('ignore', 'log', 'warn', 'throw') .default(DEFAULT_OPTIONS.onInlineAuthors), + onUntruncatedBlogPost: Joi.string() + .equal('ignore', 'log', 'warn', 'throw') + .default(DEFAULT_OPTIONS.onUntruncatedBlogPost), }).default(DEFAULT_OPTIONS); export function validateOptions({ 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 02e98f0b1e3b..fd7622f072c9 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 @@ -521,6 +521,7 @@ declare module '@docusaurus/plugin-content-blog' { authorsBasePath: string; /** The behavior of Docusaurus when it finds inline authors. */ onInlineAuthors: 'ignore' | 'log' | 'warn' | 'throw'; + onUntruncatedBlogPost: 'ignore' | 'log' | 'warn' | 'throw'; }; export type UserFeedXSLTOptions = diff --git a/website/_dogfooding/dogfooding.config.ts b/website/_dogfooding/dogfooding.config.ts index d31bce0776d7..d1731f2851a6 100644 --- a/website/_dogfooding/dogfooding.config.ts +++ b/website/_dogfooding/dogfooding.config.ts @@ -99,6 +99,7 @@ export const dogfoodingPluginInstances: PluginConfig[] = [ : defaultReadingTime({content, options: {wordsPerMinute: 5}}), onInlineTags: 'warn', onInlineAuthors: 'ignore', + onUntruncatedBlogPost: 'ignore', tags: 'tags.yml', } satisfies BlogOptions, ], diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index 9b2d50d96d2e..915e2b13ddce 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/website/docs/api/plugins/plugin-content-blog.mdx @@ -85,6 +85,7 @@ Accepted fields: | `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the blog post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub `actions/checkout`, use`fetch-depth: 0`. | | `tags` | `string \| false \| null \| undefined` | `tags.yml` | Path to the YAML tags file listing pre-defined tags. Relative to the blog content directory. | | `onInlineTags` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts contain inline tags (not appearing in the list of pre-defined tags, usually `tags.yml`). | +| `onUntruncatedBlogPost` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts does not contain truncate marker | ```mdx-code-block diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 26a3e265f0af..f5ee6cf703bf 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -475,6 +475,7 @@ export default async function createConfigAsync() { blog: { // routeBasePath: '/', path: 'blog', + onUntruncatedBlogPost: 'throw', showLastUpdateAuthor: true, showLastUpdateTime: true, editUrl: ({locale, blogDirPath, blogPath}) => { From 28790f38aaa6c423ea724a51016a935c26bacfdc Mon Sep 17 00:00:00 2001 From: OzakIOne Date: Mon, 5 Aug 2024 15:52:35 +0000 Subject: [PATCH 2/9] refactor: apply lint autofix --- project-words.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/project-words.txt b/project-words.txt index 8ff86be90d0e..cd6bf780bfec 100644 --- a/project-words.txt +++ b/project-words.txt @@ -391,6 +391,7 @@ unlocalized Unlocalized unnormalized unswizzle +Untruncated upvotes urlset Vannicatte @@ -412,8 +413,6 @@ webpackbar webstorm Wolcott Xplorer -xslt -XSLT XSOAR Yacop yangshun From 9d35f56e7f904d8aadedfc457ad658d15168c014 Mon Sep 17 00:00:00 2001 From: ozakione <29860391+OzakIOne@users.noreply.github.com> Date: Mon, 5 Aug 2024 17:47:42 +0200 Subject: [PATCH 3/9] add test --- .../src/__tests__/options.test.ts | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts index 254d56b96b2a..5698476859d8 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts @@ -374,4 +374,45 @@ describe('validateOptions', () => { ); }); }); + + describe('onUntruncatedBlogPost', () => { + it('accepts onUntruncatedBlogPost - undefined', () => { + expect( + testValidate({onUntruncatedBlogPost: undefined}).onUntruncatedBlogPost, + ).toBe('warn'); + }); + + it('accepts onUntruncatedBlogPost - "throw"', () => { + expect( + testValidate({onUntruncatedBlogPost: 'throw'}).onUntruncatedBlogPost, + ).toBe('throw'); + }); + + it('rejects onUntruncatedBlogPost - "trace"', () => { + expect(() => + // @ts-expect-error: test + testValidate({onUntruncatedBlogPost: 'trace'}), + ).toThrowErrorMatchingInlineSnapshot( + `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + ); + }); + + it('rejects onUntruncatedBlogPost - null', () => { + expect(() => + // @ts-expect-error: test + testValidate({onUntruncatedBlogPost: 42}), + ).toThrowErrorMatchingInlineSnapshot( + `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + ); + }); + + it('rejects onUntruncatedBlogPost - 42', () => { + expect(() => + // @ts-expect-error: test + testValidate({onUntruncatedBlogPost: 42}), + ).toThrowErrorMatchingInlineSnapshot( + `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + ); + }); + }); }); From 1b444fb312fd5fba9e6a2d477e675d8f762750eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Thu, 8 Aug 2024 15:28:11 +0200 Subject: [PATCH 4/9] Update website/docs/api/plugins/plugin-content-blog.mdx --- website/docs/api/plugins/plugin-content-blog.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index 915e2b13ddce..10f0fb69f64d 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/website/docs/api/plugins/plugin-content-blog.mdx @@ -85,7 +85,7 @@ Accepted fields: | `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the blog post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub `actions/checkout`, use`fetch-depth: 0`. | | `tags` | `string \| false \| null \| undefined` | `tags.yml` | Path to the YAML tags file listing pre-defined tags. Relative to the blog content directory. | | `onInlineTags` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts contain inline tags (not appearing in the list of pre-defined tags, usually `tags.yml`). | -| `onUntruncatedBlogPost` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts does not contain truncate marker | +| `onUntruncatedBlogPost` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts do not contain a truncate marker. | ```mdx-code-block From 120b20bc5f9b27fc604c28039643ee500eea51ad Mon Sep 17 00:00:00 2001 From: ozakione <29860391+OzakIOne@users.noreply.github.com> Date: Fri, 9 Aug 2024 13:31:16 +0200 Subject: [PATCH 5/9] feat(blog): refactor with `hasTruncateMarker` --- .../src/blogUtils.ts | 38 +++++++++---------- .../src/index.ts | 5 +++ 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index d43202c744c1..a87cbd12388d 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -26,6 +26,7 @@ import { isDraft, readLastUpdateData, normalizeTags, + aliasedSitePathToRelativePath, } from '@docusaurus/utils'; import {getTagsFile} from '@docusaurus/utils-validation'; import {validateBlogPostFrontMatter} from './frontMatter'; @@ -47,21 +48,25 @@ export function truncate(fileString: string, truncateMarker: RegExp): string { return fileString.split(truncateMarker, 1).shift()!; } -function reportTruncateMarkerProblem({ - blogSourceRelative, - truncateMarker, - options, - content, +function getPath(value: BlogPost) { + return aliasedSitePathToRelativePath(value.metadata.source); +} + +export function reportTruncateMarkerProblem({ + blogPosts, + onUntruncatedBlogPost, }: { - content: string; - truncateMarker: RegExp; - blogSourceRelative: string; - options: Pick; + blogPosts: BlogPost[]; + onUntruncatedBlogPost: PluginOptions['onUntruncatedBlogPost']; }): void { - if (!truncateMarker.test(content)) { - logger.report(options.onUntruncatedBlogPost)( - logger.interpolate`Blog post path=${blogSourceRelative} is not truncated.`, - ); + const untruncatedBlogPosts = blogPosts.filter( + (p) => !p.metadata.hasTruncateMarker, + ); + if (onUntruncatedBlogPost !== 'ignore' && untruncatedBlogPosts.length > 0) { + const message = `Docusaurus found untruncated blog posts: +${untruncatedBlogPosts.map(getPath).join('\n- ')} +You can turn off this settings by setting onUntruncatedBlogPost to 'ignore' in your docusaurus config file`; + logger.report(onUntruncatedBlogPost)(message); } } @@ -246,13 +251,6 @@ async function processBlogSourceFile( parseFrontMatter, }); - reportTruncateMarkerProblem({ - blogSourceRelative, - truncateMarker, - options, - content, - }); - const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir); const lastUpdate = await readLastUpdateData( diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index ea2652c57fe8..b8b6998f4c4b 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -28,6 +28,7 @@ import { shouldBeListed, applyProcessBlogPosts, generateBlogPosts, + reportTruncateMarkerProblem, } from './blogUtils'; import footnoteIDFixer from './remark/footnoteIDFixer'; import {translateContent, getTranslationFiles} from './translations'; @@ -185,6 +186,10 @@ export default async function pluginContentBlog( options, authorsMap, ); + reportTruncateMarkerProblem({ + blogPosts, + onUntruncatedBlogPost: options.onUntruncatedBlogPost, + }); blogPosts = await applyProcessBlogPosts({ blogPosts, processBlogPosts: options.processBlogPosts, From d05bf1a44182a2705fccb12d0c72973f1acd20db Mon Sep 17 00:00:00 2001 From: OzakIOne Date: Fri, 9 Aug 2024 11:36:36 +0000 Subject: [PATCH 6/9] refactor: apply lint autofix --- project-words.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/project-words.txt b/project-words.txt index cd6bf780bfec..d8bda0b3bef1 100644 --- a/project-words.txt +++ b/project-words.txt @@ -391,6 +391,7 @@ unlocalized Unlocalized unnormalized unswizzle +untruncated Untruncated upvotes urlset From 56b71c09bc764940d917ee9f05e8679afff814c3 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 15:48:13 +0200 Subject: [PATCH 7/9] rename to reportUntruncatedBlogPosts + move after processBlogPosts --- .../docusaurus-plugin-content-blog/src/blogUtils.ts | 10 ++++------ packages/docusaurus-plugin-content-blog/src/index.ts | 10 +++++----- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index a87cbd12388d..3e26e44128b0 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -48,11 +48,7 @@ export function truncate(fileString: string, truncateMarker: RegExp): string { return fileString.split(truncateMarker, 1).shift()!; } -function getPath(value: BlogPost) { - return aliasedSitePathToRelativePath(value.metadata.source); -} - -export function reportTruncateMarkerProblem({ +export function reportUntruncatedBlogPosts({ blogPosts, onUntruncatedBlogPost, }: { @@ -64,7 +60,9 @@ export function reportTruncateMarkerProblem({ ); if (onUntruncatedBlogPost !== 'ignore' && untruncatedBlogPosts.length > 0) { const message = `Docusaurus found untruncated blog posts: -${untruncatedBlogPosts.map(getPath).join('\n- ')} +${untruncatedBlogPosts + .map((p) => aliasedSitePathToRelativePath(p.metadata.source)) + .join('\n- ')} You can turn off this settings by setting onUntruncatedBlogPost to 'ignore' in your docusaurus config file`; logger.report(onUntruncatedBlogPost)(message); } diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index b8b6998f4c4b..b930facb57df 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -28,7 +28,7 @@ import { shouldBeListed, applyProcessBlogPosts, generateBlogPosts, - reportTruncateMarkerProblem, + reportUntruncatedBlogPosts, } from './blogUtils'; import footnoteIDFixer from './remark/footnoteIDFixer'; import {translateContent, getTranslationFiles} from './translations'; @@ -186,14 +186,14 @@ export default async function pluginContentBlog( options, authorsMap, ); - reportTruncateMarkerProblem({ - blogPosts, - onUntruncatedBlogPost: options.onUntruncatedBlogPost, - }); blogPosts = await applyProcessBlogPosts({ blogPosts, processBlogPosts: options.processBlogPosts, }); + reportUntruncatedBlogPosts({ + blogPosts, + onUntruncatedBlogPost: options.onUntruncatedBlogPost, + }); const listedBlogPosts = blogPosts.filter(shouldBeListed); if (!blogPosts.length) { From 3da8f601093fcf2590eeafb44cd7da2e7b17bc90 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 15:54:01 +0200 Subject: [PATCH 8/9] Add s/plural to option name for consistency: onUntruncatedBlogPosts --- .../src/__tests__/options.test.ts | 29 ++++++++++--------- .../src/blogUtils.ts | 10 +++---- .../src/index.ts | 2 +- .../src/options.ts | 6 ++-- .../src/plugin-content-blog.d.ts | 3 +- website/_dogfooding/dogfooding.config.ts | 2 +- .../docs/api/plugins/plugin-content-blog.mdx | 2 +- website/docusaurus.config.ts | 2 +- 8 files changed, 29 insertions(+), 27 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts index 5698476859d8..b2de2306f6f9 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts @@ -375,43 +375,44 @@ describe('validateOptions', () => { }); }); - describe('onUntruncatedBlogPost', () => { - it('accepts onUntruncatedBlogPost - undefined', () => { + describe('onUntruncatedBlogPosts', () => { + it('accepts onUntruncatedBlogPosts - undefined', () => { expect( - testValidate({onUntruncatedBlogPost: undefined}).onUntruncatedBlogPost, + testValidate({onUntruncatedBlogPosts: undefined}) + .onUntruncatedBlogPosts, ).toBe('warn'); }); - it('accepts onUntruncatedBlogPost - "throw"', () => { + it('accepts onUntruncatedBlogPosts - "throw"', () => { expect( - testValidate({onUntruncatedBlogPost: 'throw'}).onUntruncatedBlogPost, + testValidate({onUntruncatedBlogPosts: 'throw'}).onUntruncatedBlogPosts, ).toBe('throw'); }); - it('rejects onUntruncatedBlogPost - "trace"', () => { + it('rejects onUntruncatedBlogPosts - "trace"', () => { expect(() => // @ts-expect-error: test - testValidate({onUntruncatedBlogPost: 'trace'}), + testValidate({onUntruncatedBlogPosts: 'trace'}), ).toThrowErrorMatchingInlineSnapshot( - `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + `""onUntruncatedBlogPosts" must be one of [ignore, log, warn, throw]"`, ); }); - it('rejects onUntruncatedBlogPost - null', () => { + it('rejects onUntruncatedBlogPosts - null', () => { expect(() => // @ts-expect-error: test - testValidate({onUntruncatedBlogPost: 42}), + testValidate({onUntruncatedBlogPosts: 42}), ).toThrowErrorMatchingInlineSnapshot( - `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + `""onUntruncatedBlogPosts" must be one of [ignore, log, warn, throw]"`, ); }); - it('rejects onUntruncatedBlogPost - 42', () => { + it('rejects onUntruncatedBlogPosts - 42', () => { expect(() => // @ts-expect-error: test - testValidate({onUntruncatedBlogPost: 42}), + testValidate({onUntruncatedBlogPosts: 42}), ).toThrowErrorMatchingInlineSnapshot( - `""onUntruncatedBlogPost" must be one of [ignore, log, warn, throw]"`, + `""onUntruncatedBlogPosts" must be one of [ignore, log, warn, throw]"`, ); }); }); diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 3e26e44128b0..65ffe5887fcd 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -50,21 +50,21 @@ export function truncate(fileString: string, truncateMarker: RegExp): string { export function reportUntruncatedBlogPosts({ blogPosts, - onUntruncatedBlogPost, + onUntruncatedBlogPosts, }: { blogPosts: BlogPost[]; - onUntruncatedBlogPost: PluginOptions['onUntruncatedBlogPost']; + onUntruncatedBlogPosts: PluginOptions['onUntruncatedBlogPosts']; }): void { const untruncatedBlogPosts = blogPosts.filter( (p) => !p.metadata.hasTruncateMarker, ); - if (onUntruncatedBlogPost !== 'ignore' && untruncatedBlogPosts.length > 0) { + if (onUntruncatedBlogPosts !== 'ignore' && untruncatedBlogPosts.length > 0) { const message = `Docusaurus found untruncated blog posts: ${untruncatedBlogPosts .map((p) => aliasedSitePathToRelativePath(p.metadata.source)) .join('\n- ')} -You can turn off this settings by setting onUntruncatedBlogPost to 'ignore' in your docusaurus config file`; - logger.report(onUntruncatedBlogPost)(message); +You can turn off this settings by setting onUntruncatedBlogPosts to 'ignore' in your docusaurus config file`; + logger.report(onUntruncatedBlogPosts)(message); } } diff --git a/packages/docusaurus-plugin-content-blog/src/index.ts b/packages/docusaurus-plugin-content-blog/src/index.ts index b930facb57df..7ae3b5a54c79 100644 --- a/packages/docusaurus-plugin-content-blog/src/index.ts +++ b/packages/docusaurus-plugin-content-blog/src/index.ts @@ -192,7 +192,7 @@ export default async function pluginContentBlog( }); reportUntruncatedBlogPosts({ blogPosts, - onUntruncatedBlogPost: options.onUntruncatedBlogPost, + onUntruncatedBlogPosts: options.onUntruncatedBlogPosts, }); const listedBlogPosts = blogPosts.filter(shouldBeListed); diff --git a/packages/docusaurus-plugin-content-blog/src/options.ts b/packages/docusaurus-plugin-content-blog/src/options.ts index 9bf48f5fa00a..11e912b68170 100644 --- a/packages/docusaurus-plugin-content-blog/src/options.ts +++ b/packages/docusaurus-plugin-content-blog/src/options.ts @@ -72,7 +72,7 @@ export const DEFAULT_OPTIONS: PluginOptions = { tags: undefined, authorsBasePath: 'authors', onInlineAuthors: 'warn', - onUntruncatedBlogPost: 'warn', + onUntruncatedBlogPosts: 'warn', }; export const XSLTBuiltInPaths = { @@ -241,9 +241,9 @@ const PluginOptionSchema = Joi.object({ onInlineAuthors: Joi.string() .equal('ignore', 'log', 'warn', 'throw') .default(DEFAULT_OPTIONS.onInlineAuthors), - onUntruncatedBlogPost: Joi.string() + onUntruncatedBlogPosts: Joi.string() .equal('ignore', 'log', 'warn', 'throw') - .default(DEFAULT_OPTIONS.onUntruncatedBlogPost), + .default(DEFAULT_OPTIONS.onUntruncatedBlogPosts), }).default(DEFAULT_OPTIONS); export function validateOptions({ 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 fd7622f072c9..578688a4595b 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 @@ -521,7 +521,8 @@ declare module '@docusaurus/plugin-content-blog' { authorsBasePath: string; /** The behavior of Docusaurus when it finds inline authors. */ onInlineAuthors: 'ignore' | 'log' | 'warn' | 'throw'; - onUntruncatedBlogPost: 'ignore' | 'log' | 'warn' | 'throw'; + /** The behavior of Docusaurus when it finds untruncated blog posts. */ + onUntruncatedBlogPosts: 'ignore' | 'log' | 'warn' | 'throw'; }; export type UserFeedXSLTOptions = diff --git a/website/_dogfooding/dogfooding.config.ts b/website/_dogfooding/dogfooding.config.ts index d1731f2851a6..94b142cae275 100644 --- a/website/_dogfooding/dogfooding.config.ts +++ b/website/_dogfooding/dogfooding.config.ts @@ -99,7 +99,7 @@ export const dogfoodingPluginInstances: PluginConfig[] = [ : defaultReadingTime({content, options: {wordsPerMinute: 5}}), onInlineTags: 'warn', onInlineAuthors: 'ignore', - onUntruncatedBlogPost: 'ignore', + onUntruncatedBlogPosts: 'ignore', tags: 'tags.yml', } satisfies BlogOptions, ], diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx index 10f0fb69f64d..50a268c2fda9 100644 --- a/website/docs/api/plugins/plugin-content-blog.mdx +++ b/website/docs/api/plugins/plugin-content-blog.mdx @@ -85,7 +85,7 @@ Accepted fields: | `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the blog post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub `actions/checkout`, use`fetch-depth: 0`. | | `tags` | `string \| false \| null \| undefined` | `tags.yml` | Path to the YAML tags file listing pre-defined tags. Relative to the blog content directory. | | `onInlineTags` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts contain inline tags (not appearing in the list of pre-defined tags, usually `tags.yml`). | -| `onUntruncatedBlogPost` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts do not contain a truncate marker. | +| `onUntruncatedBlogPosts` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts do not contain a truncate marker. | ```mdx-code-block diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index f5ee6cf703bf..f4f41427031d 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -475,7 +475,6 @@ export default async function createConfigAsync() { blog: { // routeBasePath: '/', path: 'blog', - onUntruncatedBlogPost: 'throw', showLastUpdateAuthor: true, showLastUpdateTime: true, editUrl: ({locale, blogDirPath, blogPath}) => { @@ -497,6 +496,7 @@ export default async function createConfigAsync() { blogDescription: 'Read blog posts about Docusaurus from the team', blogSidebarCount: 'ALL', blogSidebarTitle: 'All our posts', + onUntruncatedBlogPosts: 'throw', onInlineTags: process.env.DOCUSAURUS_CURRENT_LOCALE !== defaultLocale ? 'warn' From 9252af7f08c7fcde9d9e313167d3441cc856961a Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 9 Aug 2024 16:31:17 +0200 Subject: [PATCH 9/9] Add tests + better untrucated blog post message --- .../src/__tests__/blogUtils.test.ts | 105 ++++++++++++++++++ .../src/blogUtils.ts | 12 +- website/docusaurus.config.ts | 5 +- 3 files changed, 116 insertions(+), 6 deletions(-) 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 a340ec61e79e..040240641127 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/blogUtils.test.ts @@ -5,12 +5,14 @@ * LICENSE file in the root directory of this source tree. */ +import {jest} from '@jest/globals'; import {fromPartial} from '@total-typescript/shoehorn'; import { truncate, parseBlogFileName, paginateBlogPosts, applyProcessBlogPosts, + reportUntruncatedBlogPosts, } from '../blogUtils'; import type {BlogPost} from '@docusaurus/plugin-content-blog'; @@ -32,6 +34,109 @@ describe('truncate', () => { }); }); +describe('reportUntruncatedBlogPosts', () => { + function testPost({ + source, + hasTruncateMarker, + }: { + source: string; + hasTruncateMarker: boolean; + }): BlogPost { + return fromPartial({ + metadata: { + source, + hasTruncateMarker, + }, + }); + } + + it('throw for untruncated blog posts', () => { + const blogPosts = [ + testPost({source: '@site/blog/post1.md', hasTruncateMarker: false}), + testPost({source: '@site/blog/post2.md', hasTruncateMarker: true}), + testPost({ + source: '@site/blog/subDir/post3.md', + hasTruncateMarker: false, + }), + ]; + expect(() => + reportUntruncatedBlogPosts({blogPosts, onUntruncatedBlogPosts: 'throw'}), + ).toThrowErrorMatchingInlineSnapshot(` + "Docusaurus found blog posts without truncation markers: + - "blog/post1.md" + - "blog/subDir/post3.md" + + We recommend using truncation markers (\`\` or \`{/* truncate */}\`) in blog posts to create shorter previews on blog paginated lists. + Tip: turn this security off with the \`onUntruncatedBlogPosts: 'ignore'\` blog plugin option." + `); + }); + + it('warn for untruncated blog posts', () => { + const consoleMock = jest.spyOn(console, 'warn'); + + const blogPosts = [ + testPost({source: '@site/blog/post1.md', hasTruncateMarker: false}), + testPost({source: '@site/blog/post2.md', hasTruncateMarker: true}), + testPost({ + source: '@site/blog/subDir/post3.md', + hasTruncateMarker: false, + }), + ]; + expect(() => + reportUntruncatedBlogPosts({blogPosts, onUntruncatedBlogPosts: 'warn'}), + ).not.toThrow(); + + expect(consoleMock.mock.calls).toMatchInlineSnapshot(` + [ + [ + "[WARNING] Docusaurus found blog posts without truncation markers: + - "blog/post1.md" + - "blog/subDir/post3.md" + + We recommend using truncation markers (\`\` or \`{/* truncate */}\`) in blog posts to create shorter previews on blog paginated lists. + Tip: turn this security off with the \`onUntruncatedBlogPosts: 'ignore'\` blog plugin option.", + ], + ] + `); + consoleMock.mockRestore(); + }); + + it('ignore untruncated blog posts', () => { + const logMock = jest.spyOn(console, 'log'); + const warnMock = jest.spyOn(console, 'warn'); + const errorMock = jest.spyOn(console, 'error'); + + const blogPosts = [ + testPost({source: '@site/blog/post1.md', hasTruncateMarker: false}), + testPost({source: '@site/blog/post2.md', hasTruncateMarker: true}), + testPost({ + source: '@site/blog/subDir/post3.md', + hasTruncateMarker: false, + }), + ]; + expect(() => + reportUntruncatedBlogPosts({blogPosts, onUntruncatedBlogPosts: 'ignore'}), + ).not.toThrow(); + + expect(logMock).not.toHaveBeenCalled(); + expect(warnMock).not.toHaveBeenCalled(); + expect(errorMock).not.toHaveBeenCalled(); + logMock.mockRestore(); + warnMock.mockRestore(); + errorMock.mockRestore(); + }); + + it('does not throw for truncated posts', () => { + const blogPosts = [ + testPost({source: '@site/blog/post1.md', hasTruncateMarker: true}), + testPost({source: '@site/blog/post2.md', hasTruncateMarker: true}), + ]; + expect(() => + reportUntruncatedBlogPosts({blogPosts, onUntruncatedBlogPosts: 'throw'}), + ).not.toThrow(); + }); +}); + describe('paginateBlogPosts', () => { const blogPosts = [ {id: 'post1', metadata: {}, content: 'Foo 1'}, diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 65ffe5887fcd..ab7426eac589 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -59,11 +59,13 @@ export function reportUntruncatedBlogPosts({ (p) => !p.metadata.hasTruncateMarker, ); if (onUntruncatedBlogPosts !== 'ignore' && untruncatedBlogPosts.length > 0) { - const message = `Docusaurus found untruncated blog posts: -${untruncatedBlogPosts - .map((p) => aliasedSitePathToRelativePath(p.metadata.source)) - .join('\n- ')} -You can turn off this settings by setting onUntruncatedBlogPosts to 'ignore' in your docusaurus config file`; + const message = logger.interpolate`Docusaurus found blog posts without truncation markers: +- ${untruncatedBlogPosts + .map((p) => logger.path(aliasedSitePathToRelativePath(p.metadata.source))) + .join('\n- ')} + +We recommend using truncation markers (code=${``} or code=${`{/* truncate */}`}) in blog posts to create shorter previews on blog paginated lists. +Tip: turn this security off with the code=${`onUntruncatedBlogPosts: 'ignore'`} blog plugin option.`; logger.report(onUntruncatedBlogPosts)(message); } } diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index f4f41427031d..8668adef3a26 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -496,7 +496,10 @@ export default async function createConfigAsync() { blogDescription: 'Read blog posts about Docusaurus from the team', blogSidebarCount: 'ALL', blogSidebarTitle: 'All our posts', - onUntruncatedBlogPosts: 'throw', + onUntruncatedBlogPosts: + process.env.DOCUSAURUS_CURRENT_LOCALE !== defaultLocale + ? 'warn' + : 'throw', onInlineTags: process.env.DOCUSAURUS_CURRENT_LOCALE !== defaultLocale ? 'warn'