docs: add new doc on why Gatsby uses GraphQL #11787

jlengstorf · 2019-02-15T04:05:20Z

This is a new doc that walks through the process of creating increasingly more complex pages in an attempt to better illustrate why GraphQL is so useful in Gatsby.

It starts with hard-coded components, moves on to context, and ends with complex pages that have images — after showing the “hard way” of passing everything through context and still ending up with unoptimized images, etc., it then shows how GraphQL can solve for many complexity issues that would otherwise be really hard to manage as a site scales.

I wanted to get initial feedback on this now, but the plan is to add video lessons to this that will walk through building these pages.

@marcysutton @KyleAMathews @gatsbyjs/core @shannonbux @amberleyromo if I missed anything or otherwise need to revise the code, please let me know so I can address it before I make videos. 😅

Thanks!

DSchau

Looking great! Left some comments--feel free to ignore or tweak to your heart's desire 🎉

docs/docs/why-gatsby-uses-graphql.md

KyleAMathews

Nice!

Like the build up of progressively more complex examples.

KyleAMathews · 2019-02-15T16:27:01Z

docs/docs/why-gatsby-uses-graphql.md

+
+The `context` property accepts an object, and we can pass in any data we want the page to be able to access.
+
+> **NOTE:** There are a few reserved names that _cannot_ be used in `context`. They are: `path`, `matchPath`, `component`, `componentChunkName`, `pluginCreator___NODE`, and `pluginCreatorId`.


do we document this anywhere else?

Not that I'm aware of — the docs are pretty light on information about context in general. @pieh pointed me to the source code, which is where I grabbed these. https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/redux/actions.js#L134-L141

It could we good to document those elsewhere, it would work well on this page: https://www.gatsbyjs.org/docs/creating-and-modifying-pages/#pass-context-to-pages

I'll create an issue and PR for it.

shannonbux

This seems really well-written. Only suggestion I have is to have a ToC at the top. I know the doc isn't long, but each header is clear and they are all equal to each other, so I think it'd be cool to see an overview at the top. Although I suppose that could go against the purpose of the doc, which is a structured argument that needs to be read through completely to be understood. Is that accurate?

jlengstorf · 2019-02-16T00:18:47Z

@shannonbux I don't know if I have a strong opinion either way on that. I do think this is designed to make a structured argument, and I wouldn't want the ToC to imply that we're necessarily calling some of these examples "ready-to-use code samples". But it's also nice to be able to navigate between sections.

I think I'd really just like to get the tutorial-style sidebar nav working on all docs pages, personally. 😄

docs/docs/why-gatsby-uses-graphql.md

calcsam · 2019-02-19T23:01:01Z

@shannonbux it would probably make more sense to have a TOC generated programmatically from headings for all docs pages rather than individually on a per-page basis.

shannonbux · 2019-02-19T23:19:46Z

@jlengstorf makes sense to me, and @calcsam that could be cool as long as perhaps there is an opt-out ability for really short docs (like ones that fit on a page), because in that case, the ToC might take more room than its worth. I don't think it's a top priority yet.

marcysutton · 2019-02-20T00:57:44Z

a TOC generated programmatically from headings for all docs pages

That sounds like a great reusable component! I know I would have used it in the new contributing section (where there are some hard-coded). Opt-in would be the easiest transition, in my opinion, so we could play around with heuristics before automatically inserting a TOC into every docs page (n headings? Doc text length? Include subheadings?). I can file an issue for a reusable component so we can keep this post moving.

calcsam · 2019-02-20T01:02:27Z

@marcysutton optimizing heuristics and an opt-in approach seems like a great idea!

Check out https://www.gatsbyjs.org/packages/gatsby-transformer-remark/#getting-table-of-contents if you haven't seen it already --

calcsam · 2019-02-20T01:12:13Z

Also we were talking about this before in this issue: #6896

KyleAMathews · 2019-02-21T21:23:08Z

It's pretty common to support a short code like [toc] to add a table of contents at that point. Agree that always adding table of contents isn't what we want as they're only useful on long docs. Though yeah, we could also add a heuristic that e.g there's 1500+ words and > N headers.

Co-Authored-By: jlengstorf <jason@lengstorf.com>

jlengstorf · 2019-03-07T21:30:09Z

Waiting on the egghead videos to be published. Once they’re live this will be good to merge.

jlengstorf · 2019-03-08T21:57:03Z

This is ready! Can I get a final review/merge? cc @marcysutton

marcysutton

This is a fantastic doc! My only question is where it will live in the nav. Do you need to update doc-links.yml?

jlengstorf · 2019-03-08T22:24:55Z

@marcysutton ha. Yes. 😅 Let me do that really quickly.

marcysutton · 2019-03-08T22:26:06Z

Perhaps you could link to your new doc from here too? https://www.gatsbyjs.org/docs/querying-with-graphql/#why-is-graphql-so-cool

jlengstorf · 2019-03-08T23:20:48Z

@marcysutton added a few links + updated the sidebar. I think we're good to go?

marcysutton

There are a few links without trailing slashes, but that's a very minor issue. Great work @jlengstorf!

## Description Documenting limitations with React context, as per the feedback/comments in #11787. Closes #12423

muescha · 2019-03-10T02:27:05Z

Section: Add the necessary plugins to load data into GraphQL

In the egghead video you use yarn to add the plugins and yarn develop instead of gatsby develop

In the doc npm for install, but later yarn develop

It should always use one of it and also doc and video should be equal

We should stick for the rule: npm for user of Gatsby

muescha · 2019-03-10T02:28:09Z

A site node: it takes me a lot of time to find out what to use and when: npm or yarn

npm as user of Gatsby and yarn as developer?

Suggestion: There should be also a doc page about the differences and when to use what

muescha · 2019-03-10T02:39:36Z

Section: Add the necessary plugins to load data into GraphQL

The video contains more info than the text of this section. The text ends with only slug in query And the rest is missing as text before the next video

LekoArts · 2019-03-10T07:31:44Z

Suggestion: There should be also a doc page about the differences and when to use what

I think that’s out of scope of the Gatsby docs. One could google that to find the differences. And you can use both anytime, there are no „rules“ for when to use what :)

muescha · 2019-03-10T07:54:23Z

I mean in context of gatsby. If you new to npm then it is a complicated to decide.

But for example: if i use yarn as a user then I never can do gatsby develop because this uses npm

LekoArts · 2019-03-10T08:44:38Z

If you’re a npm user then you don’t have to switch except when you want to contribute to the gatsby monorepo (as it uses yarn workspaces). So only displaying npm commands everywhere is fine as it’s interchangeable with yarn.

No, you misunderstand something there. gatsby develop is available if you installed the Gatsby CLI. yarn develop and npm run develop are available if the package.json has a script called develop.

muescha · 2019-03-10T17:50:17Z

maybe we extract this npm/yarn discussion into a new issue? how we can move comments?

wardpeet added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Feb 15, 2019

DSchau approved these changes Feb 15, 2019

View reviewed changes

KyleAMathews reviewed Feb 15, 2019

View reviewed changes

shannonbux reviewed Feb 15, 2019

View reviewed changes

stefanprobst reviewed Feb 16, 2019

View reviewed changes

docs/docs/why-gatsby-uses-graphql.md Outdated Show resolved Hide resolved

marcysutton reviewed Feb 19, 2019

View reviewed changes

docs/docs/why-gatsby-uses-graphql.md Show resolved Hide resolved

marcysutton reviewed Feb 19, 2019

View reviewed changes

docs/docs/why-gatsby-uses-graphql.md Show resolved Hide resolved

marcysutton reviewed Feb 19, 2019

View reviewed changes

docs/docs/why-gatsby-uses-graphql.md Outdated Show resolved Hide resolved

jlengstorf and others added 8 commits March 7, 2019 13:16

docs: add new doc on why Gatsby uses GraphQL

8307f30

docs: update docs/docs/why-gatsby-uses-graphql.md

0746e8f

Co-Authored-By: jlengstorf <jason@lengstorf.com>

docs: update docs/docs/why-gatsby-uses-graphql.md

76f288e

Co-Authored-By: jlengstorf <jason@lengstorf.com>

docs: update docs/docs/why-gatsby-uses-graphql.md

052019b

Co-Authored-By: jlengstorf <jason@lengstorf.com>

docs: update docs/docs/why-gatsby-uses-graphql.md

87bdd86

Co-Authored-By: jlengstorf <jason@lengstorf.com>

docs: switch to npm and mention reserved props

a9766ee

docs: update description of data per @stefanprobst’s feedback

d76defb

docs: embed egghead videos

43f39f7

jlengstorf force-pushed the docs/why-gql branch from 3b8daac to 43f39f7 Compare March 7, 2019 21:28

jlengstorf marked this pull request as ready for review March 7, 2019 21:30

jlengstorf requested a review from a team March 7, 2019 21:30

fix: update video embed URLs

7296cc8

marcysutton approved these changes Mar 8, 2019

View reviewed changes

This was referenced Mar 8, 2019

Docs: Make note of reserved names in context object #12423

Closed

document reserved words in React context #12424

Merged

docs: update sidebar and add links

5a791c8

jlengstorf requested a review from a team as a code owner March 8, 2019 23:20

marcysutton approved these changes Mar 8, 2019

View reviewed changes

Jason Lengstorf and others added 5 commits March 8, 2019 15:26

fix: trailing slash

1688906

fix: trailing slash

be04408

fix: trailing slash

97b75ee

fix: trailing slashes

0b13f83

fix: trailing slash

95469a4

jlengstorf merged commit b645b25 into gatsbyjs:master Mar 8, 2019

jlengstorf deleted the docs/why-gql branch March 8, 2019 23:28

muescha mentioned this pull request Mar 10, 2019

docs(www): Change to Gatsby develop #12443

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add new doc on why Gatsby uses GraphQL #11787

docs: add new doc on why Gatsby uses GraphQL #11787

jlengstorf commented Feb 15, 2019

DSchau left a comment

KyleAMathews left a comment

KyleAMathews Feb 15, 2019

jlengstorf Feb 15, 2019

marcysutton Mar 8, 2019

shannonbux left a comment

jlengstorf commented Feb 16, 2019

calcsam commented Feb 19, 2019

shannonbux commented Feb 19, 2019

marcysutton commented Feb 20, 2019

calcsam commented Feb 20, 2019

calcsam commented Feb 20, 2019

KyleAMathews commented Feb 21, 2019

jlengstorf commented Mar 7, 2019

jlengstorf commented Mar 8, 2019

marcysutton left a comment

jlengstorf commented Mar 8, 2019

marcysutton commented Mar 8, 2019

jlengstorf commented Mar 8, 2019

marcysutton left a comment

muescha commented Mar 10, 2019 •

edited

muescha commented Mar 10, 2019

muescha commented Mar 10, 2019 •

edited

LekoArts commented Mar 10, 2019

muescha commented Mar 10, 2019

LekoArts commented Mar 10, 2019

muescha commented Mar 10, 2019


		The `context` property accepts an object, and we can pass in any data we want the page to be able to access.

		> NOTE: There are a few reserved names that _cannot_ be used in `context`. They are: `path`, `matchPath`, `component`, `componentChunkName`, `pluginCreator___NODE`, and `pluginCreatorId`.

docs: add new doc on why Gatsby uses GraphQL #11787

docs: add new doc on why Gatsby uses GraphQL #11787

Conversation

jlengstorf commented Feb 15, 2019

DSchau left a comment

Choose a reason for hiding this comment

KyleAMathews left a comment

Choose a reason for hiding this comment

KyleAMathews Feb 15, 2019

Choose a reason for hiding this comment

jlengstorf Feb 15, 2019

Choose a reason for hiding this comment

marcysutton Mar 8, 2019

Choose a reason for hiding this comment

shannonbux left a comment

Choose a reason for hiding this comment

jlengstorf commented Feb 16, 2019

calcsam commented Feb 19, 2019

shannonbux commented Feb 19, 2019

marcysutton commented Feb 20, 2019

calcsam commented Feb 20, 2019

calcsam commented Feb 20, 2019

KyleAMathews commented Feb 21, 2019

jlengstorf commented Mar 7, 2019

jlengstorf commented Mar 8, 2019

marcysutton left a comment

Choose a reason for hiding this comment

jlengstorf commented Mar 8, 2019

marcysutton commented Mar 8, 2019

jlengstorf commented Mar 8, 2019

marcysutton left a comment

Choose a reason for hiding this comment

muescha commented Mar 10, 2019 • edited

muescha commented Mar 10, 2019

muescha commented Mar 10, 2019 • edited

LekoArts commented Mar 10, 2019

muescha commented Mar 10, 2019

LekoArts commented Mar 10, 2019

muescha commented Mar 10, 2019

muescha commented Mar 10, 2019 •

edited

muescha commented Mar 10, 2019 •

edited