Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(blog): add onUntruncatedBlogPosts blog options #10375

Merged
merged 10 commits into from
Aug 9, 2024
Merged

feat(blog): add onUntruncatedBlogPosts blog options #10375

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bbb522d
feat: onUntruncatedBlogPost blog options
OzakIOne Aug 5, 2024
28790f3
refactor: apply lint autofix
OzakIOne Aug 5, 2024
9d35f56
add test
OzakIOne Aug 5, 2024
1b444fb
Update website/docs/api/plugins/plugin-content-blog.mdx
slorber Aug 8, 2024
120b20b
feat(blog): refactor with `hasTruncateMarker`
OzakIOne Aug 9, 2024
d05bf1a
refactor: apply lint autofix
OzakIOne Aug 9, 2024
6513c3a
Merge branch 'main' into ozaki/truncate
slorber Aug 9, 2024
56b71c0
rename to reportUntruncatedBlogPosts + move after processBlogPosts
slorber Aug 9, 2024
3da8f60
Add s/plural to option name for consistency: onUntruncatedBlogPosts
slorber Aug 9, 2024
9252af7
Add tests + better untrucated blog post message
slorber Aug 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions packages/docusaurus-plugin-content-blog/src/__tests__/options.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]"`,
);
});
});
});
25 changes: 25 additions & 0 deletions packages/docusaurus-plugin-content-blog/src/blogUtils.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<PluginOptions, 'onUntruncatedBlogPost'>;
}): void {
if (!truncateMarker.test(content)) {
logger.report(options.onUntruncatedBlogPost)(
logger.interpolate`Blog post path=${blogSourceRelative} is not truncated.`,
);
}
}
Copy link
Collaborator

@slorber slorber Aug 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't run this Regex against the content twice: this can be expensive and is useless work. We already run it later in the blog post processing to compute the hasTruncateMarker meta attribute.

Note that in the future we'll probably handle that with Remark (the RegExp is the historical solution).

I'd prefer if:

  • we emit the warning based on blogPost.metadata.hasTruncateMarker
  • we emit a single report for all the blog posts
  • we explain in the message that this can be turned off with the blog onUntruncatedBlogPost: 'ignore' option. Many sites run with untruncated blogs on purpose, let's give them a better upgrading experience if warn is the default.

The function should rather be something like this:

function reportTruncateMarkerProblem({
  blogPosts,
  onUntruncatedBlogPost,
}: {
  blogPosts: BlogPost[],
  onUntruncatedBlogPost: PluginOptions['onUntruncatedBlogPost']
}): void {
  const untruncatedBlogPosts = blogPosts.filter(p => !p.metadata.hasTruncateMarker)
  if (onUntruncatedBlogPost !== "ignore" && onUntruncatedBlogPost.length > 0) {
    const message = `Blabla there are untruncated blog posts:
${untruncatedBlogPosts.map(getPath).join('\n- ')}
Blabla additional help`
    logger.report(options.onUntruncatedBlogPost)(message);
  }
}


export function paginateBlogPosts({
blogPosts,
basePageUrl,
Expand Down Expand Up @@ -228,6 +246,13 @@ async function processBlogSourceFile(
parseFrontMatter,
});

reportTruncateMarkerProblem({
blogSourceRelative,
truncateMarker,
options,
content,
});

const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir);

const lastUpdate = await readLastUpdateData(
Expand Down
4 changes: 4 additions & 0 deletions packages/docusaurus-plugin-content-blog/src/options.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
tags: undefined,
authorsBasePath: 'authors',
onInlineAuthors: 'warn',
onUntruncatedBlogPost: 'warn',
};

export const XSLTBuiltInPaths = {
Expand Down Expand Up @@ -240,6 +241,9 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
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({
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 =
Expand Down
3 changes: 1 addition & 2 deletions project-words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,7 @@ unlocalized
Unlocalized
unnormalized
unswizzle
Untruncated
upvotes
urlset
Vannicatte
Expand All @@ -412,8 +413,6 @@ webpackbar
webstorm
Wolcott
Xplorer
xslt
XSLT
XSOAR
Yacop
yangshun
Expand Down
1 change: 1 addition & 0 deletions website/_dogfooding/dogfooding.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@ export const dogfoodingPluginInstances: PluginConfig[] = [
: defaultReadingTime({content, options: {wordsPerMinute: 5}}),
onInlineTags: 'warn',
onInlineAuthors: 'ignore',
onUntruncatedBlogPost: 'ignore',
tags: 'tags.yml',
} satisfies BlogOptions,
],
Expand Down
1 change: 1 addition & 0 deletions website/docs/api/plugins/plugin-content-blog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
slorber marked this conversation as resolved.
Show resolved Hide resolved

```mdx-code-block
</APITable>
Expand Down
1 change: 1 addition & 0 deletions website/docusaurus.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,7 @@ export default async function createConfigAsync() {
blog: {
// routeBasePath: '/',
path: 'blog',
onUntruncatedBlogPost: 'throw',
showLastUpdateAuthor: true,
showLastUpdateTime: true,
editUrl: ({locale, blogDirPath, blogPath}) => {
Expand Down