From 39b0992ea860b92068ffd4bdf7634a44013f7958 Mon Sep 17 00:00:00 2001 From: ajayns Date: Thu, 15 Feb 2018 21:30:00 +0530 Subject: [PATCH 1/6] Add documentation for mapping --- docs/docs/gatsby-config.md | 142 ++++++++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 1 deletion(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index 456e9a78b612d..70e2b0274bbd2 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -85,7 +85,147 @@ See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby. ## mapping -TODO +--- +title: Gatsby Config +--- + +Site configuration options for a Gatsby site are placed in a file at the root of the project folder called `gatsby-config.js`. + +_Note: There are many sample configs which may be helpful to reference in the different [Gatsby Example Websites](https://github.com/gatsbyjs/gatsby/tree/master/examples)._ + +## Configuration options + +Options available to set within `gatsby-config.js` include: + +1. siteMetadata (object) +2. plugins (array) +3. pathPrefix (string) +4. polyfill (boolean) +5. mapping (object) +6. proxy (object) + +## siteMetadata + +When you want to reuse common pieces of data across the site (for example, your site title), you can store that data in `siteMetadata`: + +```javascript +module.exports = { + siteMetadata: { + title: `Gatsby`, + siteUrl: `https://www.gatsbyjs.org`, + description: `Blazing-fast static site generator for React`, + }, +}; +``` + +This way you can store it in one place, and pull it whenever you need it. If you ever need to update the info, you only have to change it here. + +See a fuller description and sample usage in [Gatsby.js Tutorial Part Four](/tutorial/part-four/#data-in-gatsby). + +## plugins + +Plugins are Node.js packages that implement Gatsby APIs. The config file accepts an array of plugins. Some plugins may need only to be listed by name, while others may take options (see the docs for individual plugins). + +```javascript +module.exports = { + plugins: [ + `gatsby-plugin-react-helmet`, + { + resolve: `gatsby-source-filesystem`, + options: { + name: `docs`, + path: `${__dirname}/../docs/`, + }, + }, + ], +}; +``` + +See more about [Plugins](/docs/plugins/) for more on utilizing plugins, and to see available official and community plugins. + +## pathPrefix + +It's common for sites to be hosted somewhere other than the root of their domain. Say we have a Gatsby site at `example.com/blog/`. In this case, we would need a prefix (`/blog`) added to all paths on the site. + +```javascript +module.exports = { + // Note: it must *not* have a trailing slash. + pathPrefix: `/blog`, +}; +``` + +See more about [Adding a Path Prefix](/docs/path-prefix/). + +## polyfill + +Gatsby uses the ES6 Promise API. Because some browsers don't support this, Gatsby includes a Promise polyfill by default. + +If you'd like to provide your own Promise polyfill, you can set `polyfill` to false. + +```javascript +module.exports = { + polyfill: false, +}; +``` + +See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby. + +## mapping + +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 + } + } + } + } +} +``` + +## proxy + +Setting the proxy config option will tell the development server to proxy any unknown requests to your specified server. For example: + +```javascript +module.exports = { + proxy: { + prefix: "/api", + url: "http://examplesite.com/api/", + }, +}; +``` + +See more about [Proxying API Requests in Development](/docs/api-proxy/). + ## proxy From 695d569cf293613312c2090c3e6926fafab9cb65 Mon Sep 17 00:00:00 2001 From: ajayns Date: Thu, 15 Feb 2018 21:36:25 +0530 Subject: [PATCH 2/6] Fix glitch in pasted code --- docs/docs/gatsby-config.md | 103 ------------------------------------- 1 file changed, 103 deletions(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index 70e2b0274bbd2..b5a67388d57ee 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -85,93 +85,6 @@ See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby. ## mapping ---- -title: Gatsby Config ---- - -Site configuration options for a Gatsby site are placed in a file at the root of the project folder called `gatsby-config.js`. - -_Note: There are many sample configs which may be helpful to reference in the different [Gatsby Example Websites](https://github.com/gatsbyjs/gatsby/tree/master/examples)._ - -## Configuration options - -Options available to set within `gatsby-config.js` include: - -1. siteMetadata (object) -2. plugins (array) -3. pathPrefix (string) -4. polyfill (boolean) -5. mapping (object) -6. proxy (object) - -## siteMetadata - -When you want to reuse common pieces of data across the site (for example, your site title), you can store that data in `siteMetadata`: - -```javascript -module.exports = { - siteMetadata: { - title: `Gatsby`, - siteUrl: `https://www.gatsbyjs.org`, - description: `Blazing-fast static site generator for React`, - }, -}; -``` - -This way you can store it in one place, and pull it whenever you need it. If you ever need to update the info, you only have to change it here. - -See a fuller description and sample usage in [Gatsby.js Tutorial Part Four](/tutorial/part-four/#data-in-gatsby). - -## plugins - -Plugins are Node.js packages that implement Gatsby APIs. The config file accepts an array of plugins. Some plugins may need only to be listed by name, while others may take options (see the docs for individual plugins). - -```javascript -module.exports = { - plugins: [ - `gatsby-plugin-react-helmet`, - { - resolve: `gatsby-source-filesystem`, - options: { - name: `docs`, - path: `${__dirname}/../docs/`, - }, - }, - ], -}; -``` - -See more about [Plugins](/docs/plugins/) for more on utilizing plugins, and to see available official and community plugins. - -## pathPrefix - -It's common for sites to be hosted somewhere other than the root of their domain. Say we have a Gatsby site at `example.com/blog/`. In this case, we would need a prefix (`/blog`) added to all paths on the site. - -```javascript -module.exports = { - // Note: it must *not* have a trailing slash. - pathPrefix: `/blog`, -}; -``` - -See more about [Adding a Path Prefix](/docs/path-prefix/). - -## polyfill - -Gatsby uses the ES6 Promise API. Because some browsers don't support this, Gatsby includes a Promise polyfill by default. - -If you'd like to provide your own Promise polyfill, you can set `polyfill` to false. - -```javascript -module.exports = { - polyfill: false, -}; -``` - -See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby. - -## mapping - 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: ``` @@ -225,19 +138,3 @@ module.exports = { ``` See more about [Proxying API Requests in Development](/docs/api-proxy/). - - -## proxy - -Setting the proxy config option will tell the development server to proxy any unknown requests to your specified server. For example: - -```javascript -module.exports = { - proxy: { - prefix: "/api", - url: "http://examplesite.com/api/", - }, -}; -``` - -See more about [Proxying API Requests in Development](/docs/api-proxy/). From a8477467c94bb9affca1288dace26f2207af112d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 16 Feb 2018 10:52:51 -0800 Subject: [PATCH 3/6] Update gatsby-config.md --- docs/docs/gatsby-config.md | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index b5a67388d57ee..eb2c66b025d84 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -35,7 +35,7 @@ This way you can store it in one place, and pull it whenever you need it. If you See a fuller description and sample usage in [Gatsby.js Tutorial Part Four](/tutorial/part-four/#data-in-gatsby). -## plugins +## Plugins Plugins are Node.js packages that implement Gatsby APIs. The config file accepts an array of plugins. Some plugins may need only to be listed by name, while others may take options (see the docs for individual plugins). @@ -69,7 +69,7 @@ module.exports = { See more about [Adding a Path Prefix](/docs/path-prefix/). -## polyfill +## Polyfill Gatsby uses the ES6 Promise API. Because some browsers don't support this, Gatsby includes a Promise polyfill by default. @@ -83,28 +83,44 @@ module.exports = { See more about [Browser Support](/docs/browser-support/#polyfills) in Gatsby. -## mapping +## Mapping node types -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: +Gatsby includes an advanced feature that lets you create "mappings" between node types. -``` +For instance, imagine you have a multi-author markdown blog where you want to "link" from each blog post to the author information stored in a yaml file named `author.yaml`: + +```markdown +--- title: A blog post author: Kyle Mathews +--- + +A treatsie on the efficacy of bezoar for treating agricultural pesticide poisoning. ``` -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: +author.yaml +```yaml +- id: Kyle Mathews + bio: Founder @ GatsbyJS. Likes tech, reading/writing, founding things. Blogs at bricolage.io. + avatar: avatars/kyle-mathews.jpeg + twitter: "@kylemathews" ``` + +You can map between the `author` field in `frontmatter` to the id in the `author.yaml` objects by adding to your `gatsby-config.js`: + +```javascript module.exports = { + plugins: [...], mapping: { "MarkdownRemark.frontmatter.author": `AuthorYaml`, }, } ``` -This enables you to query data from both sources together: +Gatsby then uses this mapping when creating the GraphQL schema to enable you to query data from both sources: -``` +```graphql query BlogPost($slug: String!) { markdownRemark(fields: {slug: {eq: $slug}}) { html @@ -113,7 +129,7 @@ query BlogPost($slug: String!) { } frontmatter { title - author { + author { # This now links to the author object id fields { slug From 70b856d1b135b487c694b3d11ab254d762c1363f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 16 Feb 2018 10:54:03 -0800 Subject: [PATCH 4/6] format --- docs/docs/gatsby-config.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index eb2c66b025d84..e56820606925a 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -95,7 +95,7 @@ title: A blog post author: Kyle Mathews --- -A treatsie on the efficacy of bezoar for treating agricultural pesticide poisoning. +A treatsie on the efficacy of bezoar for treating agricultural pesticide poisoning. ``` author.yaml @@ -122,21 +122,22 @@ Gatsby then uses this mapping when creating the GraphQL schema to enable you to ```graphql query BlogPost($slug: String!) { - markdownRemark(fields: {slug: {eq: $slug}}) { - html + markdownRemark(fields: { slug: { eq: $slug } }) { + html + fields { + slug + } + frontmatter { + title + author { + # This now links to the author object + id fields { - slug - } - frontmatter { - title - author { # This now links to the author object - id - fields { - slug - } - } + slug } + } } + } } ``` From 269dbf99e309808a5d27ee96926487f7dcd1c928 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 16 Feb 2018 10:55:53 -0800 Subject: [PATCH 5/6] Update gatsby-config.md --- docs/docs/gatsby-config.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index e56820606925a..0e0792c04b0e1 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -103,7 +103,6 @@ author.yaml ```yaml - id: Kyle Mathews bio: Founder @ GatsbyJS. Likes tech, reading/writing, founding things. Blogs at bricolage.io. - avatar: avatars/kyle-mathews.jpeg twitter: "@kylemathews" ``` @@ -132,9 +131,8 @@ query BlogPost($slug: String!) { author { # This now links to the author object id - fields { - slug - } + bio + twitter } } } From ca32da8a3f96ec8b568dfa6eeff8c06d0656dff3 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 16 Feb 2018 10:56:11 -0800 Subject: [PATCH 6/6] Update gatsby-config.md --- docs/docs/gatsby-config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/gatsby-config.md b/docs/docs/gatsby-config.md index 0e0792c04b0e1..fead62d5e3717 100644 --- a/docs/docs/gatsby-config.md +++ b/docs/docs/gatsby-config.md @@ -139,7 +139,7 @@ query BlogPost($slug: String!) { } ``` -## proxy +## Proxy Setting the proxy config option will tell the development server to proxy any unknown requests to your specified server. For example: