Gatsby: [docs] Add `mapping` documentation

[fk]

https://www.gatsbyjs.org/docs/gatsby-config/#mapping
Ref. #3129

[ajayns]

Hey! I'd love to work on this!

[m-allanson]

That's great, thanks!

[ajayns]

@KyleAMathews mentioned as an example the mapping done directly between nodes in gatsbyjs.org, an author field in markdown is mapped to an authors.yaml file. What exactly can you do once it's mapped, can you give me a bit clearer explanation of what happens in the back?

Also any suggestions on what to include in the documentation? @m-allanson @fk

[fk]

What exactly can you do once it's mapped

Query data with GraphQL. 🎉
Let me try to walk you through what @KyleAMathews referred to in https://github.com/gatsbyjs/gatsby/issues/3129#issuecomment-361369994:

1. docs/blog/author.yaml is sourced via gatsby-source-filesystem https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/www/gatsby-config.js#L11-L16 and gatsby-transformer-yaml: https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/www/gatsby-config.js#L39
2. After we set up mapping in https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/www/gatsby-config.js#L7-L9
3. we can query for the author fields in https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/www/src/templates/template-blog-post.js#L314-L337

… given that the author field in a blog posts Markdown Frontmatter matches an ID in authors.yaml, e.g. https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md has "Kostas Bariotis" set as author, which matches the id in https://github.com/gatsbyjs/gatsby/blob/4edf11f19d7a3ca163c7d99b37bb3e7192068642/docs/blog/author.yaml#L9-L12

Note that we currently only map to id, see https://github.com/gatsbyjs/gatsby/issues/3129#issuecomment-360927436

[ajayns]

@fk Thank you so much for such a detailed and clear explanation. This makes everything so much understandable now.

[ajayns]

To query between nodes, Gatsby has a mapping feature which allows you to link two different nodes by id and then you can query with GraphQL. For instance, if you have a couple of blog posts which have author id in the frontmatter:

title: A blog post
author: Kyle Mathews

And you have a list of authors and their details stored in authors.yaml, you can map between author in frontmatter to id in authors.yaml file by:

module.exports = {
  mapping: {
    "MarkdownRemark.frontmatter.author": `AuthorYaml`,
  },
}

This enables you to query data from both sources together:

query BlogPost($slug: String!) {
    markdownRemark(fields: {slug: {eq: $slug}}) {
        html
        fields {
            slug
        }
        frontmatter {
            title
            author {
                id
                fields {
                    slug
                }
            }
        }
    }
}

[ajayns]

@KyleAMathews @fk @m-allanson I've written up a rough idea of what should be added to the documentation. Any suggestions? I'll go on to making a PR once you review it!

[pieh]

@ajayns Maybe it's worth mentioning that mapping doesn't have to be 1-1 relationship (single blog post has single author) and can be 1-N (single blog post can have multiple authors - then authors field in frontmatter in your example should be array of author ids)? Probably not in introduction to this feature (to not overwhelm with too much information). This can be added at later date, just keep this in mind as this:

allows you to link two different nodes by id

is only "half" of what mapping can do.

[ajayns]

I was looking a for a simple way to explain what mapping does. Any suggestions on how I should rephrase it then? @pieh

[pieh]

Not sure really - I already learned that writing docs is hard :) Maybe don't include details about linking 2 nodes by id in introduction and just say that it links nodes. And then add more details for specific scenarios (1-1 and 1-N) in seperate sub sections?

[fk]

Thanks for chiming in @pieh!

@ajayns I think what @pieh suggested is a good way to split up general and more detailed information. Do you want to get a PR going with what you already did and we continue the discussion over there?

[ajayns]

Sure! I'm on it right now! @fk

[m-allanson]

Done in #4054, thanks @ajayns 🎉