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.

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(pages): add support for missing SEO front matter + improve SEO docs #9071

Merged
merged 6 commits into from
Jun 15, 2023

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Jun 15, 2023

Motivation

Ensure all content plugins have normalized support for these shared front matter: title, description, keywords, image

Pages:

  • Ensure title/description front matter works
  • Add missing support for keywords/image

Documentation:

Test Plan

preview

@slorber slorber added the pr: documentation This PR works on the website or other text documents in the repo. label Jun 15, 2023
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 15, 2023
@netlify
Copy link

netlify bot commented Jun 15, 2023

[V2]

Name Link
🔨 Latest commit 4b4dd95
🔍 Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/648b19d5ac998a00080d9d74
😎 Deploy Preview https://deploy-preview-9071--docusaurus-2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

@github-actions
Copy link

github-actions bot commented Jun 15, 2023

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO PWA Report
/ 🟠 63 🟢 97 🟢 92 🟢 100 🟠 89 Report
/docs/installation 🟠 76 🟢 100 🟢 92 🟢 100 🟠 89 Report

website/docs/seo.mdx Outdated Show resolved Hide resolved
@@ -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

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

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:

@thadguidry
Copy link
Contributor

And yes, makes things absolutely much more clearer! I'll continue to see if there might be gaps in coverage for a few plugin API links, or maybe you could open a clean up issue for your team.

@slorber slorber changed the title docs: improve SEO docs regarding usage of other head tags feat(pages): add support for missing SEO front matter + improve front matter docs Jun 15, 2023
@slorber slorber added pr: new feature This PR adds a new API or behavior. and removed pr: documentation This PR works on the website or other text documents in the repo. labels Jun 15, 2023
@slorber slorber changed the title feat(pages): add support for missing SEO front matter + improve front matter docs feat(pages): add support for missing SEO front matter + improve SEO docs Jun 15, 2023
@github-actions
Copy link

github-actions bot commented Jun 15, 2023

Size Change: +269 B (0%)

Total Size: 1.04 MB

Filename Size Change
website/build/assets/js/main.********.js 785 kB +269 B (0%)
ℹ️ View Unchanged
Filename Size
website/.docusaurus/globalData.json 101 kB
website/build/assets/css/styles.********.css 113 kB
website/build/index.html 40.9 kB

compressed-size-action

@slorber slorber merged commit 9866af7 into main Jun 15, 2023
@slorber slorber deleted the slorber/docs-seo-metadata branch June 15, 2023 14:07
@@ -234,6 +235,15 @@ export default function pluginContentPages(
`${docuHash(aliasedSource)}.json`,
);
},
// Assets allow to convert some relative images paths to
Copy link
Contributor

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 with relative paths, perhaps most especially in the API doc pages for plugin-content-pages and additionally maybe an Admonition on the /docs/static-assets page, which does mention require() but skips saying anything about relative paths ? Anyways, just noting this since indeed relative paths are 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Provide documentation on configuring .jsonld files to be loaded as script
3 participants