feat(pages): add support for missing SEO front matter + improve SEO docs #9071
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| --- | ||
| title: custom SEO title | ||
| description: custom SEO description | ||
| keywords: [custom, keywords] | ||
| image: ./local-image.png | ||
| --- | ||
|
|
||
| # SEO tests | ||
|
|
||
| Using page SEO front matter: | ||
|
|
||
| ```yaml | ||
| title: custom SEO title | ||
| description: custom SEO description | ||
| keywords: [custom, keywords] | ||
| image: ./local-image.png | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. The `metadata` attribute is a convenient shortcut to declare `<meta>` tags, but it is also possible to inject arbitrary tags in `<head>` with the `headTags` attribute. | ||
|
|
||
| ```js title="docusaurus.config.js" | ||
| module.exports = { | ||
| themeConfig: { | ||
| // 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', | ||
| }), | ||
| }, | ||
| ], | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
@@ -37,13 +64,24 @@ Similar to [global metadata](#global-metadata), Docusaurus also allows for the a | |
| # A cooking guide | ||
|
|
||
| <head> | ||
| <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... | ||
| ``` | ||
|
|
||
| Docusaurus automatically adds `description`, `title`, canonical URL links, and other useful metadata to each Markdown page. They are configurable through [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter): | ||
|
|
||
| ```md | ||
| --- | ||
|
|
@@ -58,7 +96,17 @@ When creating your React page, adding these fields in `Layout` would also improv | |
|
|
||
| :::tip | ||
|
|
||
| Prefer to use [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) for fields like `description` and `keywords`: Docusaurus will automatically apply this to both `description` and `og:description`, while you would have to manually declare two metadata tags when using the `<head>` tag. | ||
|
|
||
| ::: | ||
|
|
||
| :::info | ||
|
|
||
| The official plugins all support the following [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter): `title`, `description`, `keywords` and `image`. Refer to their respective API documentation for additional [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) support: | ||
|
|
||
| - [Docs front matter](./api/plugins/plugin-content-docs.mdx#markdown-front-matter) | ||
| - [Blog front matter](./api/plugins/plugin-content-blog.mdx#markdown-front-matter) | ||
| - [Pages front matter](./api/plugins/plugin-content-pages.mdx#markdown-front-matter) | ||
|
|
||
| ::: | ||
|
|
||
|
|
@@ -74,6 +122,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" /> | ||
|
There was a problem hiding this comment. Since this is generally about improving SEO docs. And One thing I noticed above on line 61 is the mention of I think the general link for the feature would be appropriate here I think: 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 There was a problem hiding this comment. I'm not sure how this comment is related to the 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> | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instead of a code comment here only, we might also consider a light mention about Assets and
require()calls withrelative paths, perhaps most especially in the API doc pages forplugin-content-pagesand additionally maybe an Admonition on the/docs/static-assetspage, which does mentionrequire()but skips saying anything aboutrelative paths? Anyways, just noting this since indeedrelative pathsare one of the tricky things that I had to figure out on my own with Docusaurus' default asset paths handling! Maybe it's Caveats section could be expanded slightly, dunno.