Skip to content

feat(pages): add support for missing SEO front matter + improve SEO docs #9071

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

Merged
slorber merged 6 commits into from
Jun 15, 2023
Merged

feat(pages): add support for missing SEO front matter + improve SEO docs #9071

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9132698
improve SEO docs
slorber Jun 15, 2023
9453d83
Update website/docs/seo.mdx
slorber Jun 15, 2023
460ab57
Add support for missing shared metadata in MDX pages: title, descript…
slorber Jun 15, 2023
ccbb29d
add useful front matter SEO linking
slorber Jun 15, 2023
bc068e1
broken links
slorber Jun 15, 2023
4b4dd95
empty
slorber Jun 15, 2023
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
57 changes: 53 additions & 4 deletions website/docs/seo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,40 @@ Docusaurus supports search engine optimization in a variety of ways.

## Global metadata {#global-metadata}

Provide global meta attributes for the entire site through the [site configuration](./configuration.mdx#site-metadata). The metadata will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value.
Provide global meta attributes for the entire site through the [site configuration](./configuration.mdx#site-metadata). The metadata will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value. The `metadata` attribute is a convenient shortcut to declare `<meta>` tags, but it is also possible inject arbitrary tags in `<head>` with the `headTags` attribute.

```js title="docusaurus.config.js"
module.exports = {
themeConfig: {
metadata: [{name: 'keywords', content: 'cooking, blog'}],
// This would become <meta name="keywords" content="cooking, blog"> in the generated HTML
// Declare some <meta> tags
metadata: [
{name: 'keywords', content: 'cooking, blog'},
{name: 'twitter:card', content: 'summary_large_image'},
],
headTags: [
// Declare a <link> preconnect tag
{
tagName: 'link',
attributes: {
rel: 'preconnect',
href: 'https://example.com',
},
},
// Declare some json-ld structured data
{
tagName: 'script',
attributes: {
type: 'application/ld+json',
},
innerHTML: JSON.stringify({
'@context': 'https://schema.org/',
'@type': 'Organization',
name: 'Meta Open Source',
url: 'https://opensource.fb.com/',
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
}),
},
],
},
};
```
Expand All @@ -37,7 +64,18 @@ Similar to [global metadata](#global-metadata), Docusaurus also allows for the a
# A cooking guide

<head>
<meta name="keywords" content="cooking, blog">
<meta name="keywords" content="cooking, blog" />
<meta name="twitter:card" content="summary_large_image" />
<link rel="preconnect" href="https://example.com" />
<script type="application/ld+json">
{JSON.stringify({
'@context': 'https://schema.org/',
'@type': 'Organization',
name: 'Meta Open Source',
url: 'https://opensource.fb.com/',
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
})}
</script>
</head>

Some content...
Expand Down Expand Up @@ -74,6 +112,17 @@ export default function page() {
<Layout title="Page" description="A React page demo">
<Head>
<meta property="og:image" content="image.png" />
<meta name="twitter:card" content="summary_large_image" />
Copy link
Contributor

@thadguidry thadguidry Jun 15, 2023

Choose a reason for hiding this comment

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

Since this is generally about improving SEO docs. And front matter is a pretty big deal for this, we should also in this same PR try to clean up some missing links about front matter.

One thing I noticed above on line 61 is the mention of front matter. That should probably be turned into a link to the page on front matter. In general, I've noticed we are pretty bad at just typing names, when they really should be links to their respective pages, especially anything like plugin, api, etc.

I think the general link for the feature would be appropriate here I think:
https://docusaurus.io/docs/markdown-features#front-matter

But I also notice we don't have a link to the API when we describe front matter on that feature section! Which should have a link to the API for the plugin, right? https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter

But we DO have an API link on the Create a Doc section about Doc front matter

Copy link
Collaborator Author

@slorber slorber Jun 15, 2023

Choose a reason for hiding this comment

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

I'm not sure how this comment is related to the twitter:card meta? 🤔

Will add links to front matter

Note: the SEO page is generic so it can only link to the generic front matter page.

It is normal that a docs page links to docs-specific front matter. Each plugin can have its own front matter.

To not bias toward a single plugin I'll add links to all the API ref supporting front matter:

<link rel="preconnect" href="https://example.com" />
<script type="application/ld+json">
{JSON.stringify({
'@context': 'https://schema.org/',
'@type': 'Organization',
name: 'Meta Open Source',
url: 'https://opensource.fb.com/',
logo: 'https://opensource.fb.com/img/logos/Meta-Open-Source.svg',
})}
</script>
</Head>
{/* ... */}
</Layout>
Expand Down