feat(docs): Add schema customization docs

[stefanprobst]

This adds a guide for the schema customization APIs. It would probably benefit from having a couple more concrete usecases, but it's a start.

[m-allanson]

Wow this is really great! Very clear and comprehensive. I've ignored your [WIP] label and added a few comments, I hope that's ok

[m-allanson]

Could this link to some external docs on field configs?

[stefanprobst]

Good idea! Not sure where to link though? To graphql-js docs (which is not 100% the same syntax), or graphql-compose docs (which is the better option, but we don't mention it anywhere else in the docs, so might be confusing?

[stefanprobst]

@muescha why did you close this?

[muescha]

@stefanprobst sorry - i was not aware that i clicked on some close issue button - sorry

here my nitpicks

[LekoArts]

Things people regularly want to do (looking at Reddit, Issues, Spectrum, Discord etc.) and should definitely be in here with fitting headings (for search and SEO):

• Setting default values (example: Optional frontmatter item like draft)
• Downloading images with GraphQL APIs (like e.g. Download images from Prismic to use in gatsby-image #14076)

[marcysutton]

Great piece! I added some suggestions for wording adjustments, and heading level changes. Thanks for putting this together!

[LekoArts]

Another idea/request:

One defines an ID in the frontmatter of markdown files and Gatsby will pass that onto the source plugin so that it can fetch that data. Usecase: Pulling all data from TMDB and then mapping/filtering for that ID takes way too much time. The source plugin then should query the individual endpoint with the ID on demand so that the schema in the end only has data for these IDs from the frontmatter. Currently you'd have to know which data to fetch from the API to be able to query it.

[freiksenet]

@marcysutton I'm not sure what exactly we can add to conclusion, I feel the guide kinda covers too much and that's it's such a wall of text :(

I feel we could improve this doc by splitting it into "guide" and "cookbook" sections. Guide would be like a tutorial to defining your types and cookbook will have more advanced solution covered.

I'd rather have that in a separate PR though, because I feel this doc is super valuable to have (so we can refer people to it). So let's merge it and I'll split it in a follow up PR.

[marcysutton]

I feel we could improve this doc by splitting it into "guide" and "cookbook" sections. Guide would be like a tutorial to defining your types and cookbook will have more advanced solution covered.

Agreed that is fine for a separate PR! We would like to add GraphQL recipes, and I could see schema customization recipes being useful too.

My only outstanding request for this PR is to link to Github issues for updating the docs, so people know those needs exist when browsing Github. It would help to add some high-level details of what needs to be updated, too, to point them in the right direction.