Docs for relationships need more examples, clearer docs, probably a guide

[adamavenir]

Summary

Gatsby has some powerful features for creating relationships between data, but each of the ones I have encountered have a real need for more thorough documentation. The docs for these features were ultimately not quite clear enough for me as an intermediate gatsby user working on my third gatsby project.

There would be tremendous value in a single guide explaining the options someone would have in using the various methods for creating relationships (the mapping and @link approaches, as well as more manual ways of creating relationships), along with walkthroughs.

You can see some of the confusion in #21678. The difficulty the widyakumara was having are different from the things that were hangups for me, but it was fairly clear between each of our experiences that there’s just too many assumptions baked into the docs at the present..

I still don’t even understand how to get the mapping feature work. (Though after getting @link to work, I probably would have an easier time going back and figuring it out, and I also think some of the challenge might come from the added complexity of using multiple markdown+frontmatter sets, which in and of itself was a little tricky.)

In summary, the following would be valuable:

• An explanatory guide to the various options for creating relationships in Gatsby
• A walkthrough for each approach
• How to use different markdown data sets alongside each other
• Improve documentation and examples for mapping and @link features

Motivation

As someone who has worked with a dozen different static site generators over the years, these are very valuable features which make gatsby extremely powerful.

Once we were able to figure out to use the @link decorator, it’s been a dream to work with and amazingly simple to use, but it took a lot of trial-and-error to get there. To me, that means there’s a pretty huge ROI for improving the docs in this area. Which is great!

Draft the doc

• Write the doc, following the format listed in these resources:
  • Overview on contributing to documentation
  • Docs Templates
  • Example of a similar article
• Add the article to the docs sidebar under the [parent doc] section.

Open a pull request

• Open a pull request with your work including the words "closes #[this issue's number]" in the pull request description

[blainekasten]

cc @gatsbyjs/learning

[kenold]

I second that. I was creating a site and needed to create a relationship between books and authors but had to use WordPress (unfortunately). I spend over 2 hours reading the mapping (object) doc but couldn't find the answer.

[marcysutton]

We have the Schema Customization workflow slated for next quarter, so this could fit nicely into that work. Thanks for filing the issue!

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[zjp]

After repeatedly failing to get the example author mapping to work, I eventually decided that porting everything I had thus far written to the example in gatsby/examples/graphql-reference was a better use of my time than continuing to diagnose. Until that point I had verified that I was, in fact, following the docs to the letter. I really do not want to think of myself as someone that cannot follow simple instructions, so I don't know what happened.

I'm loving Gatsby otherwise.

[jlarmstrongiv]

Are there any other resources, examples, issues, etc. for building relationships in gatsby? I’m unable to get my project to work so I’m duplicating data for now (unsustainable). Would definitely appreciate more guidance 😄

[adamavenir]

@jlarmstrongiv Here's a gist using the example from my project, which uses quite a few different foreignkey relations. https://gist.github.com/adamavenir/38f1785aaeb8591a2f161bb840a75e6e

[thekevinbrown]

Are there any examples for @link with a union type? ^

[thekevinbrown]

For anyone stumbling on this later, the solution is in that other issue, and I've provided some additional questions that aren't clear to me from the docs there that might help refine them.