Skip to content

Commit

Permalink
Some minor edits (#3586)
Browse files Browse the repository at this point in the history
* Some minor edits

I also think it could be cool to explain just a few use cases that answer this question: "Why is GraphQL so cool?"

I also expected to see code examples for image stuff. Also, a random thing about colons that I learned last year is this:

a full sentence must precede the colon :)

* Tweak
  • Loading branch information
shannonbux authored and KyleAMathews committed Jan 18, 2018
1 parent 53c05d0 commit 2cec6f5
Showing 1 changed file with 17 additions and 18 deletions.
35 changes: 17 additions & 18 deletions docs/docs/querying-with-graphql.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ to you.

Gatsby uses GraphQL to enable [page and layout
components](/docs/building-with-components/) to declare what data they and their
sub-components need. Gatsby then handles making sure that data is available in
sub-components need. Then, Gatsby makes that data available in
the browser when needed by your components.

## What does a GraphQL query look like?
Expand All @@ -33,7 +33,7 @@ GraphQL lets you ask for the exact data you need. Queries look like JSON:
}
```

Which returns:
Which returns this:

```json
{
Expand Down Expand Up @@ -69,12 +69,12 @@ export const query = graphql`
```
The result of the query is automatically inserted into your React component
on the `data` prop. GraphQL and Gatsby lets you ask for data and then
on the `data` prop. GraphQL and Gatsby let you ask for data and then
immediately start using it.
## How to learn GraphQL
Gatsby might be the first time you've seen GraphQL! We hope you love it as much
Your experience developing with Gatsby might be the first time you've seen GraphQL! We hope you love it as much
as we do and find it useful for all your projects.

When starting out with GraphQL, we recommend the following two tutorials:
Expand All @@ -84,18 +84,18 @@ When starting out with GraphQL, we recommend the following two tutorials:

[The official Gatsby tutorial](/tutorial/part-four/) also includes an introduction to using GraphQL specifically with Gatsby.

## How does GraphQL and Gatsby work together?
## How do GraphQL and Gatsby work together?

One of the great things about GraphQL is how flexible it is. People use GraphQL
with [many different programming languages](http://graphql.org/code/) and for web and native apps.

Most people using GraphQL run it on a server to respond live to requests for
Most people run GraphQL on a server to respond live to requests for
data from clients. You define a schema (a schema is a formal way of describing
the shape of your data) for your GraphQL server and then your GraphQL resolvers
retrieve data from databases and/or other APIs.

Gatsby is unique that it uses GraphQL at _build-time_ and _not_ for live
sites. This means you don't need to run additional services (e.g. a database
Gatsby uses GraphQL at _build-time_ and _not_ for live
sites. This is unique, and it means you don't need to run additional services (e.g. a database
and node.js service) to use GraphQL for production websites.
Gatsby is a great framework for building apps so it's possible and encouraged
Expand All @@ -106,18 +106,18 @@ a live GraphQL server from the browser.

Most usages of GraphQL involve manually creating a GraphQL schema.

With Gatsby, we instead use plugins which fetch data from different sources
which we use to automatically _infer_ a GraphQL schema.
With Gatsby, we use plugins which fetch data from different sources. We then use that data
to automatically _infer_ a GraphQL schema.

If you give Gatsby data that looks like:
If you give Gatsby data that looks like this:

```json
{
"title": "A long long time ago"
}
```

Gatsby will create a schema that looks something like:
Gatsby will create a schema that looks something like this:

```
title: String
Expand All @@ -126,17 +126,16 @@ title: String
This makes it easy to pull data from anywhere and immediately start writing
GraphQL queries against your data.

This _can_ cause confusion though as some data sources allow you to define
a schema but parts of that schema might still not be recreated in Gatsby if
there's not yet any data added for that part of the schema.
This _can_ cause confusion as some data sources allow you to define
a schema even when there's not any data added for parts or all of the schema. If parts of the data haven't been added, then those parts of the schema might not be recreated in Gatsby.

## Powerful data transformations

GraphQL enables another unique feature of Gatsby — it lets you control data transformations with arguments to your queries. Some examples.
GraphQL enables another unique feature of Gatsby — it lets you control data transformations with arguments to your queries. Some examples follow.

### Formatting dates

People often store dates like "2018-01-05" but want to display the date in some other form like "January 5th, 2018". One way of doing this is to load a date formatting JavaScript library into the browser. With Gatsby's GraphQL layer you can instead do the formatting at query time like:
People often store dates like "2018-01-05" but want to display the date in some other form like "January 5th, 2018". One way of doing this is to load a date-formatting JavaScript library into the browser. Or, with Gatsby's GraphQL layer, you can do the formatting at query-time like:
```graphql
{
Expand All @@ -146,7 +145,7 @@ People often store dates like "2018-01-05" but want to display the date in some
### Markdown
Gatsby has _transformer_ plugins which can transform data from one form to another. A common example is markdown. If you install [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/) then in your queries, you can specify you want the transformed HTML version instead of markdown:
Gatsby has _transformer_ plugins which can transform data from one form to another. A common example is markdown. If you install [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/), then in your queries, you can specify you want the transformed HTML version instead of markdown:
```graphql
markdownRemark {
Expand Down

0 comments on commit 2cec6f5

Please sign in to comment.