Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add `mapping` documentation #4007

Closed
fk opened this issue Feb 13, 2018 · 13 comments

Comments

Projects
4 participants
@fk
Copy link
Contributor

commented Feb 13, 2018

@ajayns

This comment has been minimized.

Copy link
Contributor

commented Feb 14, 2018

Hey! I'd love to work on this!

@m-allanson

This comment has been minimized.

Copy link
Member

commented Feb 14, 2018

That's great, thanks!

@ajayns

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

@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

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2018

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 #3129 (comment):

  1. docs/blog/author.yaml is sourced via gatsby-source-filesystem
    {
    resolve: `gatsby-source-filesystem`,
    options: {
    name: `docs`,
    path: `${__dirname}/../docs/`,
    },
    and gatsby-transformer-yaml:
    `gatsby-transformer-yaml`,
  2. After we set up mapping in
    mapping: {
    "MarkdownRemark.frontmatter.author": `AuthorYaml`,
    },
  3. we can query for the author fields in
    author {
    id
    bio
    twitter
    avatar {
    childImageSharp {
    resolutions(
    width: 63
    height: 63
    quality: 75
    traceSVG: {
    turdSize: 10
    background: "#f6f2f8"
    color: "#e0d6eb"
    }
    ) {
    ...GatsbyImageSharpResolutions_tracedSVG
    }
    }
    }
    fields {
    slug
    }
    }

… 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

- id: Kostas Bariotis
bio: Senior full stack engineer, @devitconf & @skgnodejs co-organizer, http://devastation.tv host, creator of http://janitr.net & others
avatar: avatars/kostas-bariotis.jpg
twitter: "@kbariotis"

image

Note that we currently only map to id, see #3129 (comment)

@ajayns

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

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

@ajayns

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

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

@pieh

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

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

This comment has been minimized.

Copy link
Contributor Author

commented Feb 15, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Feb 15, 2018

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

@m-allanson

This comment has been minimized.

Copy link
Member

commented Feb 16, 2018

Done in #4054, thanks @ajayns 🎉

@m-allanson m-allanson closed this Feb 16, 2018

Documentation Project automation moved this from To do to Done Feb 16, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.