feat(blog): Add `frontMatter.title_meta` to override title for SEO #10586

ilg-ul · 2024-10-16T23:02:18Z

Pre-flight checklist

I have read the Contributing Guidelines on pull requests.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

The new frontMatter property allows to generate shorter titles in the <head> section, for both docs & blogs, while keeping the existing long titles for the page headers & other places where blog post titles are used.

Test Plan

none

Test links

none

Related issues/PRs

document title vs blog post title and SEO meta title #10578

netlify · 2024-10-16T23:04:34Z

✅ [V2]

Name	Link
🔨 Latest commit	`d3804c1`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/67235fc0ca0ae80008027ec9
😎 Deploy Preview	https://deploy-preview-10586--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2024-10-16T23:07:03Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🟠 53	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🟠 51	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 75	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 48	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 65	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 75	🟢 100	🟢 100	🟠 86	Report

ilg-ul · 2024-10-16T23:07:42Z

It looks like title_meta was already used in some tests.

Perhaps title_head would be a more appropriate name, the new setting applies to <head><title>, which is not part of <meta>.

slorber

Almost LGTM but I'd prefer that you don't modify the docs plugin, and you don't add this to blog metadata (only front matter should be enough, it's temporary so it's less code to remove in the future)

The tests are fine and did not use title_meta, but if you add it to metadata, you have many tests and snapshots to modify. Run yarn test --watch locally until tests pass. Once you remove the metadata, you probably don't need to change the existing tests anymore.

However you need to add frontMatter.title to the validation schema and add an unit test for it.

Also need to write docs

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

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

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

slorber · 2024-10-17T08:11:20Z

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

+    /**
+     * Used to generate the <head><title> and <meta>.
+     */
+    title_meta?: string;


packages/docusaurus-theme-classic/src/theme/BlogPostPage/Metadata/index.tsx

packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx

ilg-ul · 2024-10-17T12:48:15Z

I think that it would be helpful to decide what is the final desired behaviour, and try to implement it incrementally, without having to reverse changes.

Before submitting the PR I did some experimentation and, from my limited point of view, I covered all use cases that I could imagined, but submitted only part of the changes, as a first step.

First, do you agree that we should do our best to have a consistent solution for both docs and blog posts?

Then, do you agree that we should have at least one solution for defining shorter titles, to be passed for SEO usage, at the same time with longer titles, to be displayed in the web, and this solution once implemented, should be documented and remain in the code?

As far as I can tell, I can see two solutions:

add title_meta to both docs and blog posts frontMatter; the logic behind computing and using title remains unchanged, except when passed to <PageMetadata ...> in those two places, when title_meta is preferred.

To achieve this, the current changes achieve this; if you think that some can be simplified, ok, we can simplify them.

slightly adjust the logic behind processing titles, to prefer the H1 header as the web page title, and get the SEO title from frontMatter.title

To achieve this, in addition to the suggested changes, two more lines need to be changed, the frontMatter.title and contentTitle must be swapped.

The blog title should be computed as (the comment is the current line):

// const title = frontMatter.title ?? contentTitle ?? parsedBlogFileName.text;
const title = contentTitle ?? frontMatter.title ?? parsedBlogFileName.text;

The docs title should be computed similarly:

// const title: string = frontMatter.title ?? contentTitle ?? baseID;
const title: string = contentTitle ?? frontMatter.title ?? baseID;

If we implement both cases, I think that it is better to have two separate variables, one to store the title shown on the web pages (metadata.title) and one for the title passed to SEO (metadata.title_meta).

For consistency reasons, I would use the same mechanism for both docs and blog posts.

The only detail not covered by the above solution is filtering out markdown syntax from the H1 header, but I think that this can be added in a later step.

If I totally misunderstood the subject and you have a different approach in mind, perhaps we should wait for the final solution and avoid adding now a temporary workaround to be later removed.

For my use case I would probably go for using title_meta in all blog posts and docs (now I use title_seo, so it is just a matter of renaming). As for the main title, now I use frontMatter.title in blog posts and H1 in docs; I might replace the H1, but I'm not sure.

Please advise how to proceed.

slorber · 2024-10-18T17:07:35Z

title_meta is a temporary workaround, that we'll remove as a breaking change once I find a solution.

I don't want to introduce this to docs because we don't need it, and this would be another thing to remove in the future. I prefer a temporary small inconsistency than a larger temporary but consistent change.

Also, reversing the title logic is a breaking change. I don't want to do such a breaking change when we can solve the problem in a retrocompatible way without disrupting existing usage and asking users to modify their md files. The frontMatter.title has always been meant to be the source of truth for SEO, and in theory we shouldn't need another attribute.

Please just add frontMatter.title_meta to the blog and don't do any non-retrocompatible change to the behavior

ilg-ul · 2024-10-18T17:39:10Z

Please just add frontMatter.title_meta to the blog

Done.

ilg-ul · 2024-10-18T17:41:36Z

Please note a small naming inconsistency, the docs frontMatter properties pagination_label and sidebar_label are prefixed, while title_head is suffixed.

alvinometric · 2024-10-29T15:22:03Z

I thought this was already possible by using an h1 on the page and a title in the frontmatter?

slorber · 2024-10-29T15:46:12Z

@alvinometric afaik it's not the case for blog posts (only docs), and I explained why here: #10578 (reply in thread)

slorber · 2024-10-31T10:31:17Z

Please note a small naming inconsistency, the docs frontMatter properties pagination_label and sidebar_label are prefixed, while title_head is suffixed.

I think it's fine and better this way. We want to "group" things by concerns with a prefix. title and title_meta are grouped together, while sidebar_ are also grouped together. Considering this front matter is temporary and we'll try to get rid of it, I don't expect us to have a logical meta_ group of front matter attributes.

ilg-ul · 2024-10-31T14:38:10Z

Did you document this somewhere? Or it'll remain undocumented?

slorber · 2024-10-31T21:04:28Z

Yes I edited your PR

ilg-ul · 2024-10-31T21:08:23Z

I see. But the new text does not mention that this is a temporary solution.

Add title_meta to frontMatter & metadata.

76000d7

ilg-ul requested review from slorber and Josh-Cena as code owners October 16, 2024 23:02

facebook-github-bot added the CLA Signed Signed Facebook CLA label Oct 16, 2024

slorber requested changes Oct 17, 2024

View reviewed changes

ilg-ul added 3 commits October 18, 2024 20:32

revert docs changes

a732cda

simplify blog changes, do not change metadata

62c93b8

remove empty line

8e9b5a3

ilg-ul changed the title ~~Add title_meta to frontMatter & metadata.~~ Add title_meta to blog frontMatter Oct 18, 2024

ilg-ul requested a review from slorber October 18, 2024 18:30

slorber added the pr: new feature This PR adds a new API or behavior. label Oct 29, 2024

slorber changed the title ~~Add title_meta to blog frontMatter~~ feat(blog): Add title_meta to blog frontMatter Oct 31, 2024

slorber added 2 commits October 31, 2024 11:40

add title_meta to blog frontMatter schema

e4e6bb8

add title_meta to docs

d3804c1

slorber changed the title ~~feat(blog): Add title_meta to blog frontMatter~~ feat(blog): Add frontMatter.title_meta to override title for SEO Oct 31, 2024

slorber approved these changes Oct 31, 2024

View reviewed changes

slorber merged commit 5cf2c39 into facebook:main Oct 31, 2024
38 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(blog): Add `frontMatter.title_meta` to override title for SEO #10586

feat(blog): Add `frontMatter.title_meta` to override title for SEO #10586

ilg-ul commented Oct 16, 2024

netlify bot commented Oct 16, 2024 •

edited

Loading

github-actions bot commented Oct 16, 2024 •

edited

Loading

ilg-ul commented Oct 16, 2024 •

edited

Loading

slorber left a comment

slorber Oct 17, 2024

ilg-ul commented Oct 17, 2024 •

edited

Loading

slorber commented Oct 18, 2024 •

edited

Loading

ilg-ul commented Oct 18, 2024

ilg-ul commented Oct 18, 2024

alvinometric commented Oct 29, 2024

slorber commented Oct 29, 2024

slorber commented Oct 31, 2024

ilg-ul commented Oct 31, 2024 •

edited

Loading

slorber commented Oct 31, 2024

ilg-ul commented Oct 31, 2024

feat(blog): Add frontMatter.title_meta to override title for SEO #10586

feat(blog): Add frontMatter.title_meta to override title for SEO #10586

Conversation

ilg-ul commented Oct 16, 2024

Pre-flight checklist

Motivation

Test Plan

Test links

Related issues/PRs

netlify bot commented Oct 16, 2024 • edited Loading

✅ [V2]

github-actions bot commented Oct 16, 2024 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

ilg-ul commented Oct 16, 2024 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

slorber Oct 17, 2024

Choose a reason for hiding this comment

ilg-ul commented Oct 17, 2024 • edited Loading

slorber commented Oct 18, 2024 • edited Loading

ilg-ul commented Oct 18, 2024

ilg-ul commented Oct 18, 2024

alvinometric commented Oct 29, 2024

slorber commented Oct 29, 2024

slorber commented Oct 31, 2024

ilg-ul commented Oct 31, 2024 • edited Loading

slorber commented Oct 31, 2024

ilg-ul commented Oct 31, 2024

feat(blog): Add `frontMatter.title_meta` to override title for SEO #10586

feat(blog): Add `frontMatter.title_meta` to override title for SEO #10586

netlify bot commented Oct 16, 2024 •

edited

Loading

github-actions bot commented Oct 16, 2024 •

edited

Loading

ilg-ul commented Oct 16, 2024 •

edited

Loading

ilg-ul commented Oct 17, 2024 •

edited

Loading

slorber commented Oct 18, 2024 •

edited

Loading

ilg-ul commented Oct 31, 2024 •

edited

Loading