[docs] Add advanced tutorials for SEO and social sharing cards #20964
Conversation
FlorianDr
changed the title
|
Cool 😎 Thanks for doing this! I'll defer to @gatsbyjs/learning for the content review 👍 |
Co-Authored-By: LB <barth.laurie@gmail.com>
There was a problem hiding this comment.
Thank you so much for putting in the work to move this over from Dustin's original post and for your patience while I was away for Gatsby Days/Gathering last week!
This looks like a ton of comments but most are fairly straightforward suggestions. I'm particularly interested in making some improvements to the images' alt text. Someone from the Learning team will also walk through this tutorial to verify everything still works as expected!
| title: Search Engine Optimization (SEO) and Social Sharing Cards with Gatsby | ||
| --- | ||
|
|
||
| Perhaps you've even been approached by an SEO _expert_ who can maximize your revenue and page views just by following these **Three Simple Tricks**! However, relatively few make the concerted effort to implement SEO in their web app. This tutorial will share some of the ins and outs of SEO and how you can implement common, simple SEO patterns in your Gatsby web app, today. By the end of this post you'll know how to do the following: |
There was a problem hiding this comment.
| Perhaps you've even been approached by an SEO _expert_ who can maximize your revenue and page views just by following these **Three Simple Tricks**! However, relatively few make the concerted effort to implement SEO in their web app. This tutorial will share some of the ins and outs of SEO and how you can implement common, simple SEO patterns in your Gatsby web app, today. By the end of this post you'll know how to do the following: | |
| Perhaps you've been approached by an SEO _expert_ who can maximize your revenue and page views just by following these **Three Simple Tricks**! Relatively few people make the concerted effort to implement SEO in their web app. This tutorial will share some of the ins and outs of SEO and how you can implement common, simple SEO patterns in your Gatsby web app, today. By the end of this post you'll know how to do the following: |
Looks like the very beginning of the original text is missing. I would either add it back in or reword this along the lines of what I've suggested.
|
|
||
| ## Implementation | ||
|
|
||
| The core technology powering SEO is the humble, ubiquitiuous `meta` tag along with common tags like `title`. You've probably seen something like the below: |
There was a problem hiding this comment.
Does this take into account the feedback from Andrew Welch? It looks like Dustin didn't get to address all of it in his original PR. I know the ask was only to slightly modify Dustin's post, so I won't let this hold up merging.
There was a problem hiding this comment.
Thank you for the pointer. I will have a look at the feedback and try to incorporate it.
| /> | ||
| ``` | ||
|
|
||
| These are the _bare minimum_ requirements that should be implemented within an application's `head` tags for simple and basic SEO. However -- the following describes a powerful combo of content rendered at _build time_ powered by Gatsby and GraphQL. Let's dive in. |
There was a problem hiding this comment.
| These are the _bare minimum_ requirements that should be implemented within an application's `head` tags for simple and basic SEO. However -- the following describes a powerful combo of content rendered at _build time_ powered by Gatsby and GraphQL. Let's dive in. | |
| These are the _bare minimum_ requirements that should be implemented within an application's `head` tags for basic SEO. However, the following describes a powerful combo of content rendered at _build time_ powered by Gatsby and GraphQL. Let's dive in. |
Please remove any instances of words like "easy" or "simple". We try to make sure the docs are as friendly as we can make them and avoid making too many assumptions about readers' knowledge.
|
|
||
| ## Gatsby + GraphQL | ||
|
|
||
| GraphQL is a crucial feature enabled via Gatsby (note: you don't [_have_ to use GraphQL with Gatsby][unstructured-data]). Leveraging GraphQL to query your indexable content--wherever it lives (at build time!)--is one of the most powerful and flexible techniques enabled via Gatsby. Let's briefly look at the implemention of an extensible and flexible SEO component. |
There was a problem hiding this comment.
| GraphQL is a crucial feature enabled via Gatsby (note: you don't [_have_ to use GraphQL with Gatsby][unstructured-data]). Leveraging GraphQL to query your indexable content--wherever it lives (at build time!)--is one of the most powerful and flexible techniques enabled via Gatsby. Let's briefly look at the implemention of an extensible and flexible SEO component. | |
| GraphQL is a crucial feature enabled via Gatsby (note: you don't [_have_ to use GraphQL with Gatsby][unstructured-data]). Leveraging GraphQL to query your indexable content--wherever it lives (at build time!)--is one of the most powerful and flexible techniques enabled via Gatsby. The following sections are a brief look at the implementation of an extensible and flexible SEO component. |
Try to avoid (or update) any instances of "we" or "let's" and prefer "you" as the pronoun.
|
|
||
| ### `StaticQuery` | ||
|
|
||
| Gatsby distinguishes between page-level queries and component queries. The former can use page GraphQL queries while the latter can use a new in Gatsby v2 feature called [`StaticQuery`][gatsby-static-query]. A StaticQuery will be parsed, evaluated, and injected at _build time_ into the component that is requesting the data, allowing to fall back to sane defaults, while also providing an extensible, reusable component. |
There was a problem hiding this comment.
| Gatsby distinguishes between page-level queries and component queries. The former can use page GraphQL queries while the latter can use a new in Gatsby v2 feature called [`StaticQuery`][gatsby-static-query]. A StaticQuery will be parsed, evaluated, and injected at _build time_ into the component that is requesting the data, allowing to fall back to sane defaults, while also providing an extensible, reusable component. | |
| Gatsby distinguishes between page-level queries and component queries. The former can use page GraphQL queries while the latter can use [`StaticQuery`][gatsby-static-query]. A StaticQuery will be parsed, evaluated, and injected at _build time_ into the component that is requesting the data, allowing it to fall back to reasonable defaults, while also providing an extensible, reusable component. |
I think we should replace the word "sane" here. We don't have a specific guideline that covers it but there's room to make a kinder choice. Also, StaticQuery (and v2) are no longer new!
|
|
||
| Feel free to add whatever, or perhaps use this _very pertinent_ image: | ||
|
|
||
|  |
There was a problem hiding this comment.
|  | |
|  |
If you choose to maintain the sentence immediately preceding this image, I suggest making the alt text more specific. Anyone who can't see the image won't get the joke!
|
|
||
|  | ||
|
|
||
| the image will need to be located at `content/blog/2019-01-04-hello-world-seo/images/featured.jpg` |
There was a problem hiding this comment.
| the image will need to be located at `content/blog/2019-01-04-hello-world-seo/images/featured.jpg` | |
| The image will need to be located at `content/blog/2019-01-04-hello-world-seo/images/featured.jpg`. |
|
|
||
| To learn more about these validations, check out how to _validate_ SEO with the following tools from [Google][google-validation], [Twitter][twitter-validation], and [Facebook][facebook-validation]. | ||
|
|
||
| These SEO resources outlined in this tutorial aren't _only_ a best practice, they're also a best practice enabled, by default. Available **today** in `gatsby-starter-default`, simply use: |
There was a problem hiding this comment.
| These SEO resources outlined in this tutorial aren't _only_ a best practice, they're also a best practice enabled, by default. Available **today** in `gatsby-starter-default`, simply use: | |
| The SEO resources outlined in this tutorial aren't _only_ a best practice, they're also a best practice enabled by default. Available **today** in `gatsby-starter-default`, use: |
| These SEO resources outlined in this tutorial aren't _only_ a best practice, they're also a best practice enabled, by default. Available **today** in `gatsby-starter-default`, simply use: | ||
|
|
||
| ```shell | ||
| npx gatsby new my-new-gatsby-app |
There was a problem hiding this comment.
| npx gatsby new my-new-gatsby-app | |
| npm gatsby new my-new-gatsby-app |
This is mostly for consistency with other docs.
|
Hi, @FlorianDr! Checking in on this and to see if there's anything I can help with or clarify. |
|
@AishaBlake thank you for offering your help. I started implementing your feedback, but I haven't brought it to next review yet. I will keep you posted about it. Let me know, if it's urgent to finish it ASAP. |
wardpeet
added
the
type: documentation
|
@AishaBlake I would be keen to hear your feedback again :) Sorry for the delay with this matter. |
|
Thanks, @FlorianDr! I made some quick edits but realized I missed a larger update. The code samples should be updated to reflect the current versions. If we want folks to be able to follow along, we ought to start the tutorial off at each file's starting point in the default starter. (For example, we now use the It would also be good to point out the compatibility notes on |
|
The last thing I think this needs is to close the loop and show how'd you'd add a featured image, then what that would look like when linked on social media. This feels outside the scope of this PR, though, so I'll make an issue for it! |
There was a problem hiding this comment.
@FlorianDr I started to do this in suggestions and it was a bit much. Let me know what you think of that last commit. If you're happy with it, I'm ready to merge!
|
I'm actually going to go ahead and merge to keep this moving. Thank you so, so much for contributing, @FlorianDr. Really happy to finally get this content somewhere live! |
|
Holy buckets, @FlorianDr — we just merged your PR to Gatsby! 💪💜 Gatsby is built by awesome people like you. Let us say “thanks” in two ways:
If there’s anything we can do to help, please don’t hesitate to reach out to us: tweet at @gatsbyjs and we’ll come a-runnin’. Thanks again! |
|
@AishaBlake Thank you so much for helping me getting this over the finish line. I learned so much. |
Description
This is about moving the initial blog post by @DSchau into a new advanced tutorial and link it in the reference guide on the SEO page.
Related Issues
Fixes #14125