From 76000d75c5d2c6be21ad23c9ace9c45e10650cc9 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Thu, 17 Oct 2024 01:50:35 +0300 Subject: [PATCH 1/6] Add title_meta to frontMatter & metadata. --- packages/docusaurus-plugin-content-blog/src/blogUtils.ts | 3 +++ .../src/plugin-content-blog.d.ts | 9 +++++++++ packages/docusaurus-plugin-content-docs/src/docs.ts | 3 +++ .../src/plugin-content-docs.d.ts | 9 +++++++++ .../src/theme/BlogPostPage/Metadata/index.tsx | 2 +- .../src/theme/DocItem/Metadata/index.tsx | 2 +- 6 files changed, 26 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index ab7426eac589..15ce6a100af2 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -301,6 +301,8 @@ async function processBlogSourceFile( const date = await getDate(); const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text; + const title_meta = frontMatter.title_meta ?? frontMatter.title ?? contentTitle ?? parsedBlogFileName.text; + const description = frontMatter.description ?? excerpt ?? ''; const slug = frontMatter.slug ?? parsedBlogFileName.slug; @@ -365,6 +367,7 @@ async function processBlogSourceFile( editUrl: getBlogEditUrl(), source: aliasedSource, title, + title_meta, description, date, tags, 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 578688a4595b..ae87c060b563 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 @@ -143,6 +143,11 @@ declare module '@docusaurus/plugin-content-blog' { * @see {@link BlogPostMetadata.title} */ title?: string; + /** + * Will override the title collected from the frontMatter. + * @see {@link BlogPostMetadata.title_meta} + */ + title_meta?: string; /** * Will override the default excerpt. * @see {@link BlogPostMetadata.description} @@ -249,6 +254,10 @@ declare module '@docusaurus/plugin-content-blog' { * Used to generate the page h1 heading, tab title, and pagination title. */ readonly title: string; + /** + * Used to generate the and <meta>. + */ + readonly title_meta?: string; /** * The publish date of the post. On client side, this will be serialized * into a string. diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index e3eb7cc47f45..46936a3140e5 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -177,6 +177,8 @@ async function doProcessDocMetadata({ // pagination buttons... frontMatter.title should be used in priority over // contentTitle (because it can contain markdown/JSX syntax) const title: string = frontMatter.title ?? contentTitle ?? baseID; + // To be passed to `<PageMetadata>`. Will override the title. + const title_meta: string = frontMatter.title_meta ?? frontMatter.title ?? contentTitle ?? baseID; const description: string = frontMatter.description ?? excerpt ?? ''; @@ -224,6 +226,7 @@ async function doProcessDocMetadata({ return { id, title, + title_meta, description, source: aliasedSitePath(filePath, siteDir), sourceDirName, diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts index 806cf280ce51..620c514d5bb7 100644 --- a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts +++ b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts @@ -308,6 +308,11 @@ declare module '@docusaurus/plugin-content-docs' { * @see {@link DocMetadata.title} */ title?: string; + /** + * Will override the title collected from the frontMatter. + * @see {@link DocMetadata.title_meta} + */ + title_meta?: string; /** * Front matter tags, unnormalized. * @see {@link DocMetadata.tags} @@ -411,6 +416,10 @@ declare module '@docusaurus/plugin-content-docs' { * Used to generate the page h1 heading, tab title, and pagination title. */ title: string; + /** + * Used to generate the <head><title> and <meta>. + */ + title_meta?: string; /** * Description used in the meta. Could be an empty string (empty content) */ diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx index 26a62049b827..ca21379507de 100644 --- a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx @@ -17,7 +17,7 @@ export default function BlogPostPageMetadata(): JSX.Element { const image = assets.image ?? frontMatter.image; return ( <PageMetadata - title={title} + title={metadata.title_meta ?? title} description={description} keywords={keywords} image={image}> diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx index 3296fa747900..a139fc529276 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx @@ -13,7 +13,7 @@ export default function DocItemMetadata(): JSX.Element { const {metadata, frontMatter, assets} = useDoc(); return ( <PageMetadata - title={metadata.title} + title={metadata.title_meta ?? metadata.title} description={metadata.description} keywords={frontMatter.keywords} image={assets.image ?? frontMatter.image} From a732cdaee7633a645ecdefb1ef09d5925fadfbf6 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu <ilg@livius.net> Date: Fri, 18 Oct 2024 20:32:58 +0300 Subject: [PATCH 2/6] revert docs changes --- packages/docusaurus-plugin-content-docs/src/docs.ts | 3 --- .../src/plugin-content-docs.d.ts | 9 --------- .../src/theme/DocItem/Metadata/index.tsx | 2 +- 3 files changed, 1 insertion(+), 13 deletions(-) diff --git a/packages/docusaurus-plugin-content-docs/src/docs.ts b/packages/docusaurus-plugin-content-docs/src/docs.ts index 46936a3140e5..e3eb7cc47f45 100644 --- a/packages/docusaurus-plugin-content-docs/src/docs.ts +++ b/packages/docusaurus-plugin-content-docs/src/docs.ts @@ -177,8 +177,6 @@ async function doProcessDocMetadata({ // pagination buttons... frontMatter.title should be used in priority over // contentTitle (because it can contain markdown/JSX syntax) const title: string = frontMatter.title ?? contentTitle ?? baseID; - // To be passed to `<PageMetadata>`. Will override the title. - const title_meta: string = frontMatter.title_meta ?? frontMatter.title ?? contentTitle ?? baseID; const description: string = frontMatter.description ?? excerpt ?? ''; @@ -226,7 +224,6 @@ async function doProcessDocMetadata({ return { id, title, - title_meta, description, source: aliasedSitePath(filePath, siteDir), sourceDirName, diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts index 620c514d5bb7..806cf280ce51 100644 --- a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts +++ b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts @@ -308,11 +308,6 @@ declare module '@docusaurus/plugin-content-docs' { * @see {@link DocMetadata.title} */ title?: string; - /** - * Will override the title collected from the frontMatter. - * @see {@link DocMetadata.title_meta} - */ - title_meta?: string; /** * Front matter tags, unnormalized. * @see {@link DocMetadata.tags} @@ -416,10 +411,6 @@ declare module '@docusaurus/plugin-content-docs' { * Used to generate the page h1 heading, tab title, and pagination title. */ title: string; - /** - * Used to generate the <head><title> and <meta>. - */ - title_meta?: string; /** * Description used in the meta. Could be an empty string (empty content) */ diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx index a139fc529276..3296fa747900 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx @@ -13,7 +13,7 @@ export default function DocItemMetadata(): JSX.Element { const {metadata, frontMatter, assets} = useDoc(); return ( <PageMetadata - title={metadata.title_meta ?? metadata.title} + title={metadata.title} description={metadata.description} keywords={frontMatter.keywords} image={assets.image ?? frontMatter.image} From 62c93b8bf647896d87a54d34e082f7b835f2e95c Mon Sep 17 00:00:00 2001 From: Liviu Ionescu <ilg@livius.net> Date: Fri, 18 Oct 2024 20:34:17 +0300 Subject: [PATCH 3/6] simplify blog changes, do not change metadata --- packages/docusaurus-plugin-content-blog/src/blogUtils.ts | 2 -- .../src/plugin-content-blog.d.ts | 6 +----- .../src/theme/BlogPostPage/Metadata/index.tsx | 2 +- 3 files changed, 2 insertions(+), 8 deletions(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index 15ce6a100af2..a38460575b56 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -301,7 +301,6 @@ async function processBlogSourceFile( const date = await getDate(); const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text; - const title_meta = frontMatter.title_meta ?? frontMatter.title ?? contentTitle ?? parsedBlogFileName.text; const description = frontMatter.description ?? excerpt ?? ''; @@ -367,7 +366,6 @@ async function processBlogSourceFile( editUrl: getBlogEditUrl(), source: aliasedSource, title, - title_meta, description, date, tags, 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 ae87c060b563..1606aaa5f5e8 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 @@ -144,7 +144,7 @@ declare module '@docusaurus/plugin-content-blog' { */ title?: string; /** - * Will override the title collected from the frontMatter. + * Will be used for SEO page metadata and override BlogPostMetadata.title. * @see {@link BlogPostMetadata.title_meta} */ title_meta?: string; @@ -254,10 +254,6 @@ declare module '@docusaurus/plugin-content-blog' { * Used to generate the page h1 heading, tab title, and pagination title. */ readonly title: string; - /** - * Used to generate the <head><title> and <meta>. - */ - readonly title_meta?: string; /** * The publish date of the post. On client side, this will be serialized * into a string. diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx index ca21379507de..2eb2eeb33b0e 100644 --- a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx @@ -17,7 +17,7 @@ export default function BlogPostPageMetadata(): JSX.Element { const image = assets.image ?? frontMatter.image; return ( <PageMetadata - title={metadata.title_meta ?? title} + title={frontMatter.title_meta ?? title} description={description} keywords={keywords} image={image}> From 8e9b5a3b73e8589e018786c3ed34c2420e6d7747 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu <ilg@livius.net> Date: Fri, 18 Oct 2024 20:35:33 +0300 Subject: [PATCH 4/6] remove empty line --- packages/docusaurus-plugin-content-blog/src/blogUtils.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts index a38460575b56..ab7426eac589 100644 --- a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts +++ b/packages/docusaurus-plugin-content-blog/src/blogUtils.ts @@ -301,7 +301,6 @@ async function processBlogSourceFile( const date = await getDate(); const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text; - const description = frontMatter.description ?? excerpt ?? ''; const slug = frontMatter.slug ?? parsedBlogFileName.slug; From e4e6bb8de261b24e951cb607a7cbb466ebed9516 Mon Sep 17 00:00:00 2001 From: sebastien <lorber.sebastien@gmail.com> Date: Thu, 31 Oct 2024 11:40:57 +0100 Subject: [PATCH 5/6] add title_meta to blog frontMatter schema --- .../src/__tests__/frontMatter.test.ts | 15 +++++++++++++++ .../src/frontMatter.ts | 1 + 2 files changed, 16 insertions(+) diff --git a/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts b/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts index 9c05dcca944a..f5ca63694c65 100644 --- a/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts +++ b/packages/docusaurus-plugin-content-blog/src/__tests__/frontMatter.test.ts @@ -93,6 +93,21 @@ describe('validateBlogPostFrontMatter title', () => { {title: ''}, {title: 'title'}, ], + invalidFrontMatters: [ + [{title: null}, 'must be a string'], + [{title: false}, 'must be a string'], + ], + }); +}); + +describe('validateBlogPostFrontMatter title_meta', () => { + testField({ + prefix: 'title_meta', + validFrontMatters: [{title: ''}, {title_meta: 'title'}], + invalidFrontMatters: [ + [{title_meta: null}, 'must be a string'], + [{title_meta: false}, 'must be a string'], + ], }); }); diff --git a/packages/docusaurus-plugin-content-blog/src/frontMatter.ts b/packages/docusaurus-plugin-content-blog/src/frontMatter.ts index 6c3436198038..0e822258290b 100644 --- a/packages/docusaurus-plugin-content-blog/src/frontMatter.ts +++ b/packages/docusaurus-plugin-content-blog/src/frontMatter.ts @@ -33,6 +33,7 @@ const FrontMatterAuthorErrorMessage = const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({ id: Joi.string(), title: Joi.string().allow(''), + title_meta: Joi.string(), description: Joi.string().allow(''), tags: FrontMatterTagsSchema, date: Joi.date().raw(), From d3804c1bb0c58c7975cdc7f614f8bb3d347e2d47 Mon Sep 17 00:00:00 2001 From: sebastien <lorber.sebastien@gmail.com> Date: Thu, 31 Oct 2024 11:44:18 +0100 Subject: [PATCH 6/6] add title_meta to docs --- website/docs/api/plugins/plugin-content-docs.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/api/plugins/plugin-content-docs.mdx b/website/docs/api/plugins/plugin-content-docs.mdx index 8f26354b8189..95ef5e76f275 100644 --- a/website/docs/api/plugins/plugin-content-docs.mdx +++ b/website/docs/api/plugins/plugin-content-docs.mdx @@ -278,6 +278,7 @@ Accepted fields: | --- | --- | --- | --- | | `id` | `string` | file path (including folders, without the extension) | A unique document ID. | | `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. | +| `title_meta` | `string` | `frontMatter.title` | The SEO metadata title of your document used in `<head>` for `<title>` and `og:title`. Permits to override `frontMatter.title` when the displayed title and SEO title should be different. | | `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. | | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. | | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar/autogenerated#autogenerated-sidebar-metadata). |