` used by Gatsby to mount React to
+ `___gatsby`
+* The default layout component should be at `layouts/index.js` not
+ `layouts/default.js`
+ https://github.com/gatsbyjs/gatsby/pull/940#issuecomment-300537162
+* `this.props.children` in layout components is now a _function_
+ https://github.com/gatsbyjs/gatsby/pull/940#issuecomment-300878300
+* Change the default port for serve-build to 9000
+* Change the path to GraphiQL to `/___graphql`
### Chore
-- Upgrade Jest to v20 #935
+
+* Upgrade Jest to v20 #935
## [1.0.0-alpha14] - 2017-05-05
+
### Added
-- Use the Relay Modern compiler for extracting GraphQL queries from components.
-This allows us to now support components being added to *all* components. This
-means you can now write queries next to the views that use them. #912
-- Hook for modifying pages #863
-- New Drupal source plugin and example site #890
-- Detect if a site's plugins have changed and when they do, delete the site
-cache as it might now be invalid #927
-- New way to make connections between nodes e.g. article --> author #902
+* Use the Relay Modern compiler for extracting GraphQL queries from components.
+ This allows us to now support components being added to _all_ components. This
+ means you can now write queries next to the views that use them. #912
+* Hook for modifying pages #863
+* New Drupal source plugin and example site #890
+* Detect if a site's plugins have changed and when they do, delete the site
+ cache as it might now be invalid #927
+* New way to make connections between nodes e.g. article --> author #902
### Changed
-- Combine transformer and typegen plugins. The distinction between the two
-types of plugins has proved somewhat artificial so they were combined. Any
-typegen plugins in your `package.json` and `gatsby-config.js` need to be
-removed. #918
-- Gatsby now garbage collects old nodes. Source plugins should now "touch"
-- nodes that haven't changed #861
-- Due to adopting the Relay compiler, GraphQL query template strings need
-named "graphql" plus must be named. So if previously you wrote:
+* Combine transformer and typegen plugins. The distinction between the two types
+ of plugins has proved somewhat artificial so they were combined. Any typegen
+ plugins in your `package.json` and `gatsby-config.js` need to be removed. #918
+* Gatsby now garbage collects old nodes. Source plugins should now "touch"
+* nodes that haven't changed #861
+* Due to adopting the Relay compiler, GraphQL query template strings need named
+ "graphql" plus must be named. So if previously you wrote:
```js
export const pageQuery = `
@@ -475,175 +536,203 @@ You must now write:
```js
export const pageQuery = graphql`
-query IndexQuery {
- allMarkdownMark {
- edges {
- node {
- id
+ query IndexQuery {
+ allMarkdownMark {
+ edges {
+ node {
+ id
+ }
}
}
}
-}
`
```
-
## [1.0.0-alpha10] - 2016-11-17
+
### Added
-- Did the intitial build of the new gatsbyjs.org! It's in the `www`
- subdirectory on the 1.0 branch and is built on each push! That's my
-kind of integration testing :-) You can see the early version of the
-site at https://gatsbyjs.netlify.com/. PRs welcome!
-- Added
for page scripts. This speeds up loading scripts
- slightly by telling the browser to start downloading the scripts when
-the HTML first starts being parsed instead of when the browser reaches
-the end. This is especially helpful for large HTML documents on slow
-mobile networks. [PR](https://github.com/gatsbyjs/gatsby/pull/558)
+
+* Did the intitial build of the new gatsbyjs.org! It's in the `www` subdirectory
+ on the 1.0 branch and is built on each push! That's my kind of integration
+ testing :-) You can see the early version of the site at
+ https://gatsbyjs.netlify.com/. PRs welcome!
+* Added
for page scripts. This speeds up loading scripts slightly
+ by telling the browser to start downloading the scripts when the HTML first
+ starts being parsed instead of when the browser reaches the end. This is
+ especially helpful for large HTML documents on slow mobile networks.
+ [PR](https://github.com/gatsbyjs/gatsby/pull/558)
## Changed
-- Use namedmodulesplugin instead of recordsPath for ensuring
- deterministic builds and long-term cachability. The [previous PR adding
-support for recordsPath](https://github.com/gatsbyjs/gatsby/pull/533)
-proved unpleasant as you had to build locally and commit the outputted
-records.json which was confusing and annoying.
-[PR](https://github.com/gatsbyjs/gatsby/pull/559)
+
+* Use namedmodulesplugin instead of recordsPath for ensuring deterministic
+ builds and long-term cachability. The
+ [previous PR adding support for recordsPath](https://github.com/gatsbyjs/gatsby/pull/533)
+ proved unpleasant as you had to build locally and commit the outputted
+ records.json which was confusing and annoying.
+ [PR](https://github.com/gatsbyjs/gatsby/pull/559)
## [1.0.0-alpha9] - 2016-11-04
+
### Added
-- Put the routes module on `window` to support experimental idea. See
- this issue for more](https://github.com/gatsbyjs/gatsby/issues/537).
-[commit](https://github.com/gatsbyjs/gatsby/commit/28e84f3aed480d1f5a8f9859172d1c6f531696d4)
+
+* Put the routes module on `window` to support experimental idea. See this issue
+ for more](https://github.com/gatsbyjs/gatsby/issues/537).
+ [commit](https://github.com/gatsbyjs/gatsby/commit/28e84f3aed480d1f5a8f9859172d1c6f531696d4)
### Changed
-- Removed the package `sharp` as it's not used and is preventing Gatsby
- 1.0 from being installed on Windows.
-[commit](https://github.com/gatsbyjs/gatsby/commit/34fff74e6fb3cae88010b42f74d784382ead4031)
+
+* Removed the package `sharp` as it's not used and is preventing Gatsby 1.0 from
+ being installed on Windows.
+ [commit](https://github.com/gatsbyjs/gatsby/commit/34fff74e6fb3cae88010b42f74d784382ead4031)
## [1.0.0-alpha8] - 2016-11-01
+
### Added
-- Extension API `swOnUpdated` for when a service worker finishes
- updating. Use this to alert users of your app to reload to see the
-latest version.
-[commit](https://github.com/gatsbyjs/gatsby/commit/5173bdc5424e7c874b3f2abfad706cea2e38ebc3)
+
+* Extension API `swOnUpdated` for when a service worker finishes updating. Use
+ this to alert users of your app to reload to see the latest version.
+ [commit](https://github.com/gatsbyjs/gatsby/commit/5173bdc5424e7c874b3f2abfad706cea2e38ebc3)
### Fixed
-- hot reloading now fully works. Apparently you can't use function
- components for top-level routes on react-router with react-hot-loader
-3.0 `¯\_(ツ)_/¯` [#532](https://github.com/gatsbyjs/gatsby/pull/532) and
-[commit](https://github.com/gatsbyjs/gatsby/commit/36f2c169586ea30518639d7b1493e08e05befb73)
-- Webpack needs the help of an obscure setting `recordsPath` to preserve
- module ids across builds. Big thanks to @NekR for pointing this out to
-me. Previous to this change, loading changed JS chunks could cause a JS
-error as the module ids the new chunk expects wouldn't match the module
-ids from the older chunks.
-[#533](https://github.com/gatsbyjs/gatsby/pull/533)
+
+* hot reloading now fully works. Apparently you can't use function components
+ for top-level routes on react-router with react-hot-loader 3.0 `¯\_( ツ )_/¯`
+ [#532](https://github.com/gatsbyjs/gatsby/pull/532) and
+ [commit](https://github.com/gatsbyjs/gatsby/commit/36f2c169586ea30518639d7b1493e08e05befb73)
+* Webpack needs the help of an obscure setting `recordsPath` to preserve module
+ ids across builds. Big thanks to @NekR for pointing this out to me. Previous
+ to this change, loading changed JS chunks could cause a JS error as the module
+ ids the new chunk expects wouldn't match the module ids from the older chunks.
+ [#533](https://github.com/gatsbyjs/gatsby/pull/533)
### Changed
-- Disabled hard-source-webpack-plugin. It speeds up builds significantly
- but has been causing hard-to-debug errors while developing. We'll
-circle back to it down the road.
-[commit](https://github.com/gatsbyjs/gatsby/commit/4bc9660ac8c371d23c0295cde52002775eee5aa1)
-- Restored using ChunkManifestPlugin. It was disabled while trying to
- debug the mismatched module id bug but that being fixed, we're using
-it again.
-[commit](https://github.com/gatsbyjs/gatsby/commit/8d16905f31b80ca56db225904d60ed78c6091ca9)
-- Name modules ids in development for easier debugging. Primary benefit
- is you can see which modules are getting hot reloaded.
-[commit](https://github.com/gatsbyjs/gatsby/commit/93f6bd2c4206e71623c1a7fa007322f8dc9887be)
+
+* Disabled hard-source-webpack-plugin. It speeds up builds significantly but has
+ been causing hard-to-debug errors while developing. We'll circle back to it
+ down the road.
+ [commit](https://github.com/gatsbyjs/gatsby/commit/4bc9660ac8c371d23c0295cde52002775eee5aa1)
+* Restored using ChunkManifestPlugin. It was disabled while trying to debug the
+ mismatched module id bug but that being fixed, we're using it again.
+ [commit](https://github.com/gatsbyjs/gatsby/commit/8d16905f31b80ca56db225904d60ed78c6091ca9)
+* Name modules ids in development for easier debugging. Primary benefit is you
+ can see which modules are getting hot reloaded.
+ [commit](https://github.com/gatsbyjs/gatsby/commit/93f6bd2c4206e71623c1a7fa007322f8dc9887be)
## [1.0.0-alpha7] - 2016-10-27
+
### Fixed
-- Removed entries from the webpack config looking for
- `node_modules/gatsby/node_modules`. This was added to help when
-developing Gatsby using `npm link` but when Gatsby is installed
-regularly, it then fails the Webpack validation as
-`node_modules/gatsby/node_modules` doesn't now exist.
+
+* Removed entries from the webpack config looking for
+ `node_modules/gatsby/node_modules`. This was added to help when developing
+ Gatsby using `npm link` but when Gatsby is installed regularly, it then fails
+ the Webpack validation as `node_modules/gatsby/node_modules` doesn't now
+ exist.
## [1.0.0-alpha6] - 2016-10-27
+
### Added
-- extension API for adding types to the GraphQL schema
+
+* extension API for adding types to the GraphQL schema
[commit](https://github.com/gatsbyjs/gatsby/commit/18b8b64ed4cbe3399fb262395c0c6e6a5a16099a)
### Fixed
-- Use babel-traverse instead of using babel-plugin so that don't say
- done early when running graphql queries that have async resolvers
-[commit](https://github.com/gatsbyjs/gatsby/commit/a19677e38d1ce8ba4fb39ddff75482904f168db6)
+
+* Use babel-traverse instead of using babel-plugin so that don't say done early
+ when running graphql queries that have async resolvers
+ [commit](https://github.com/gatsbyjs/gatsby/commit/a19677e38d1ce8ba4fb39ddff75482904f168db6)
## [1.0.0-alpha5] - 2016-10-14
+
### Added
-- hard-source-webpack-plugin
+
+* hard-source-webpack-plugin
[commit](https://github.com/gatsbyjs/gatsby/commit/2c48e5c42887fecabc01c5f5b6f3dd8e06d3372f)
-- New replacement API to wrap root component (useful for Redux, et
- al.)
-[commit](https://github.com/gatsbyjs/gatsby/commit/ebd57d2bd6c39b51a455b76018737e2957e146ef)
-- yarn.lock
+* New replacement API to wrap root component (useful for Redux, et al.)
+ [commit](https://github.com/gatsbyjs/gatsby/commit/ebd57d2bd6c39b51a455b76018737e2957e146ef)
+* yarn.lock
[commit](https://github.com/gatsbyjs/gatsby/commit/5ce3321b84e912925c4705ececef6f2c817b0684)
### Changed
-- Disable extracting the Webpack chunk manifest until understand why
- this breaks updates when using Service Workers
-[commit](https://github.com/gatsbyjs/gatsby/commit/07ed5b010ad27b1816084b361f06fd0ae6a017ba)
+
+* Disable extracting the Webpack chunk manifest until understand why this breaks
+ updates when using Service Workers
+ [commit](https://github.com/gatsbyjs/gatsby/commit/07ed5b010ad27b1816084b361f06fd0ae6a017ba)
## [1.0.0-alpha4] - 2016-10-07
+
### Added
-- Add more file extensions to file/url loader config. Default to url
- loader unless it never makes sense to use data-uri e.g. favicons.
-- Use api-runner-browser for calling browser extension
- APIs/replacements. Prep for plugin system.
-- Add extension API `clientEntry` that let's site code and plugins to
- run code at the very start of client app.
+
+* Add more file extensions to file/url loader config. Default to url loader
+ unless it never makes sense to use data-uri e.g. favicons.
+* Use api-runner-browser for calling browser extension APIs/replacements. Prep
+ for plugin system.
+* Add extension API `clientEntry` that let's site code and plugins to run code
+ at the very start of client app.
### Changed
-- Add config to uglify to ignore ie8.
-- Disable building AppCache until can research if useful.
-- Turn on screw_ie8 options in UglifyJS.
+
+* Add config to uglify to ignore ie8.
+* Disable building AppCache until can research if useful.
+* Turn on screw_ie8 options in UglifyJS.
### Fixed
-- Actually use the "sources" key from gatsby-config.js for looking for
-markdown files. This will be getting an overhaul soon.
-- Don't use null-loader for css during the build-js stage as this
- prevents offline-plugin from caching files referenced in your CSS.
-- Add missing publicPath for build-html step.
+
+* Actually use the "sources" key from gatsby-config.js for looking for markdown
+ files. This will be getting an overhaul soon.
+* Don't use null-loader for css during the build-js stage as this prevents
+ offline-plugin from caching files referenced in your CSS.
+* Add missing publicPath for build-html step.
## [1.0.0-alpha3] - 2016-10-05
+
### Added
-- Introduce way to programmatically add components to `` + API to take over SSR rendering [a39c2a5](https://github.com/gatsbyjs/gatsby/commit/a39c2a5)
-- Extract webpack manifest from commons.js so it doesn't change on every
- build improving its cachability
-[0941d33](https://github.com/gatsbyjs/gatsby/commit/0941d33)
-- Always add babel-plugin-add-module-exports
+
+* Introduce way to programmatically add components to `` + API to take
+ over SSR rendering
+ [a39c2a5](https://github.com/gatsbyjs/gatsby/commit/a39c2a5)
+* Extract webpack manifest from commons.js so it doesn't change on every build
+ improving its cachability
+ [0941d33](https://github.com/gatsbyjs/gatsby/commit/0941d33)
+* Always add babel-plugin-add-module-exports
[97f083d](https://github.com/gatsbyjs/gatsby/commit/97f083d)
### Changed
-- Upgraded React Hot Loader to 3.0-beta5
+
+* Upgraded React Hot Loader to 3.0-beta5
[5185c3a](https://github.com/gatsbyjs/gatsby/commit/5185c3a)
### Fixed
-- Ensure bundle names for components and paths are unique [342030d](https://github.com/gatsbyjs/gatsby/commit/342030d)
+
+* Ensure bundle names for components and paths are unique
+ [342030d](https://github.com/gatsbyjs/gatsby/commit/342030d)
[a1dfe19](https://github.com/gatsbyjs/gatsby/commit/a1dfe19)
-- Remove old code loading config.toml
+* Remove old code loading config.toml
[66f901](https://github.com/gatsbyjs/gatsby/commit/66f901)
## [1.0.0-alpha2] - 2016-09-21
+
### Added
-- New system for specifying page layouts inspired by Jekyll.
-- `
` helper components for rendering
- correct scripts and styles in your html.js,
-- Validate at runtime gatsby-config.js and page objects.
-- Start of new plugin system.
-- New extension API: `onPostCreatePages` — called with pages after all
- pages are created. Useful for programmatically modifying pages created
-in plugins.
+
+* New system for specifying page layouts inspired by Jekyll.
+* `
` helper components for rendering correct
+ scripts and styles in your html.js,
+* Validate at runtime gatsby-config.js and page objects.
+* Start of new plugin system.
+* New extension API: `onPostCreatePages` — called with pages after all pages are
+ created. Useful for programmatically modifying pages created in plugins.
### Changed
-- Removed remaining 0.x code
-- Exit if can't find local install of Gatsby.
+
+* Removed remaining 0.x code
+* Exit if can't find local install of Gatsby.
[030f655](https://github.com/gatsbyjs/gatsby/commit/030f655075be5ad91af1dc12a05e6bd153a861df)
-- Fix folder hierarchy for looking for loaders and modules #435
-- Changed default `Config` GraphQL type to `Site` and added some
- Jekyll-inspired fields.
+* Fix folder hierarchy for looking for loaders and modules #435
+* Changed default `Config` GraphQL type to `Site` and added some Jekyll-inspired
+ fields.
## [1.0.0-alpha1] - 2016-09-02
+
### Added
-- Initial versions of new GraphQL data layer, PRPL pattern, programmatic routes, code
- splitting, supporting long-term caching of JS files.
+
+* Initial versions of new GraphQL data layer, PRPL pattern, programmatic routes,
+ code splitting, supporting long-term caching of JS files.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b76b72d17c51e..44acdeab905ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,13 +12,15 @@ If you want your issue to be resolved quickly, please include in your issue:
changes you've made there.
## Contributing
+
Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on
lerna and yarn to configure the repository for active development.
You can install the latest version of Gatsby by following these steps:
* Clone the repo, navigate to its directory.
-* ensure you have the latest version of yarn installed (>= 1.0.2) https://yarnpkg.com/en/docs/install
+* ensure you have the latest version of yarn installed (>= 1.0.2)
+ https://yarnpkg.com/en/docs/install
* Install dependencies using `yarn run bootstrap` in the root of the repo.
The usual contributing steps are:
@@ -28,14 +30,15 @@ The usual contributing steps are:
* setup up repo and Install dependencies: `yarn run bootstrap`
* Make sure tests are passing for you: `yarn test`
* Create a topic branch: `git checkout -b topics/new-feature-name`
-* Run `npm run watch` from the root of the repo to first do an initial Babel build of all packages and then watch for
- changes to packages' source code and compile these changes on-the-fly as you
- work.
-* Install [gatsby-dev-cli](/packages/gatsby-dev-cli/) globally: `yarn global add gatsby-dev-cli`
+* Run `npm run watch` from the root of the repo to first do an initial Babel
+ build of all packages and then watch for changes to packages' source code and
+ compile these changes on-the-fly as you work.
+* Install [gatsby-dev-cli](/packages/gatsby-dev-cli/) globally: `yarn global add
+ gatsby-dev-cli`
* For each of your Gatsby test sites, run the `gatsby-dev` command there to copy
the built files from your cloned copy of Gatsby. It'll watch for your changes
- to Gatsby packages and copy them into the site. For more detailed
- instructions see the [gatsby-dev-cli README](/packages/gatsby-dev-cli/)
+ to Gatsby packages and copy them into the site. For more detailed instructions
+ see the [gatsby-dev-cli README](/packages/gatsby-dev-cli/)
* Add tests and code for your changes.
* Once you're done, make sure all tests still pass: `yarn test`
* Commit and push to your fork.
@@ -45,25 +48,26 @@ The usual contributing steps are:
### Redux devtools
-Gatsby uses Redux for managing state during development and building. It's
-often helpful to see the flow of actions and builtup state for a site you're
-working on or if adding new functionality to core. We leverage
+Gatsby uses Redux for managing state during development and building. It's often
+helpful to see the flow of actions and builtup state for a site you're working
+on or if adding new functionality to core. We leverage
https://github.com/zalmoxisus/remote-redux-devtools and
https://github.com/zalmoxisus/remotedev-server to give you use the Redux
devtools extension for debugging Gatsby.
To use this, first install
[redux-devtools-extension](https://github.com/zalmoxisus/redux-devtools-extension)
-in your browser. Then in your Gatsby repo, run `npm run remotedev`. Then in
-your site directory run `REDUX_DEVTOOLS=true gatsby develop`. Depending on
-your operating system and shell, you may need to modify how you set the
+in your browser. Then in your Gatsby repo, run `npm run remotedev`. Then in your
+site directory run `REDUX_DEVTOOLS=true gatsby develop`. Depending on your
+operating system and shell, you may need to modify how you set the
`REDUX_DEVTOOLS` environment variable.
-At this point, your site will be sending Redux actions and state to the remote server.
-
-To connect to this, you need to setup the devtools extension to talk to the remote
+At this point, your site will be sending Redux actions and state to the remote
server.
+To connect to this, you need to setup the devtools extension to talk to the
+remote server.
+
First open the remote devtools.
![how to open the redux remote devtools extension](./images/open-remote-dev-tools.png)
@@ -72,16 +76,16 @@ Then click settings along the bottom menu and set the host and port.
![how to set the host/port for the remote devtools extension to connect to Gatsby](./images/remote-dev-settings.png)
-After this, the devtools extension *should* connect to the remote server and you'll
-see actions start showing up.
+After this, the devtools extension _should_ connect to the remote server and
+you'll see actions start showing up.
![gatsby redux remote devtools](./images/running-redux-devtools.png)
**Warning!! Lots of buginess**. While having this available is extremely
helpful, this setup is very buggy and fragile. There is a memory leak in the
extension that's triggered it seems every time you restart the Gatsby
-development server. Also the extension often, for no apparent reason, just
-won't show any actions from the remote server. It'll also often freeze up. The
-best solution seems to just be turning everything off and on again. Fixing up
-these tools would be very helpful for us and many others using these tools if
-someone wants to take this on!
+development server. Also the extension often, for no apparent reason, just won't
+show any actions from the remote server. It'll also often freeze up. The best
+solution seems to just be turning everything off and on again. Fixing up these
+tools would be very helpful for us and many others using these tools if someone
+wants to take this on!
diff --git a/README.md b/README.md
index a49e1ab8ba51a..0dd97114f384c 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,9 @@
## Showcase
Websites built with Gatsby:
-* [React](https://reactjs.org/) ([source](https://github.com/reactjs/reactjs.org))
+
+* [React](https://reactjs.org/)
+ ([source](https://github.com/reactjs/reactjs.org))
* [Sourcegraph](https://about.sourcegraph.com)
* [Simply](https://simply.co.za)
* [The freeCodeCamp Guide](https://guide.freecodecamp.org)
@@ -23,43 +25,65 @@ Websites built with Gatsby:
* [Segment's Blog](https://segment.com/blog/)
* [Fabric](https://meetfabric.com/)
* [Formidable](https://formidable.com/)
-* [openFDA](https://open.fda.gov/) ([source](https://github.com/FDA/open.fda.gov))
-* [ReasonML Docs](https://reasonml.github.io/) ([source](https://github.com/reasonml/reasonml.github.io))
-* [Bricolage.io](https://www.bricolage.io/) ([source](https://github.com/KyleAMathews/blog))
-* [Jamie Henson's Blog](http://jamiehenson.com/) ([source](https://github.com/jamiehenson/jh47-gatsby))
+* [openFDA](https://open.fda.gov/)
+ ([source](https://github.com/FDA/open.fda.gov))
+* [ReasonML Docs](https://reasonml.github.io/)
+ ([source](https://github.com/reasonml/reasonml.github.io))
+* [Bricolage.io](https://www.bricolage.io/)
+ ([source](https://github.com/KyleAMathews/blog))
+* [Jamie Henson's Blog](http://jamiehenson.com/)
+ ([source](https://github.com/jamiehenson/jh47-gatsby))
* [Sean Coker's Blog](https://sean.is/)
-* [Dustin Schau's Blog](https://dustinschau.com/blog/) ([source](https://github.com/dschau/blog))
+* [Dustin Schau's Blog](https://dustinschau.com/blog/)
+ ([source](https://github.com/dschau/blog))
* [The Chiedo Companies Website](https://www.chiedo.com)
-* [Damir.io](http://damir.io/) ([source](https://github.com/dvzrd/gatsby-sfiction))
+* [Damir.io](http://damir.io/)
+ ([source](https://github.com/dvzrd/gatsby-sfiction))
* [Ruben's Blog](https://vagr9k.me/) ([source](https://github.com/Vagr9K/Blog))
-* [Kostas Bariotis' Blog](https://kostasbariotis.com/) ([source](https://github.com/kbariotis/kostasbariotis.com))
+* [Kostas Bariotis' Blog](https://kostasbariotis.com/)
+ ([source](https://github.com/kbariotis/kostasbariotis.com))
* [Thao Am Private Enterprise](http://thaoam.com/)
* [Bakadono](http://bakadono.com/)
* [Travellers.cafe](https://travellers.cafe/)
-* [Oliver Benns' Portfolio](https://oliverbenns.com) ([source](https://github.com/oliverbenns/oliverbenns.com))
-* [angeloocana.com](https://angeloocana.com) ([source](https://github.com/angeloocana/angeloocana))
+* [Oliver Benns' Portfolio](https://oliverbenns.com)
+ ([source](https://github.com/oliverbenns/oliverbenns.com))
+* [angeloocana.com](https://angeloocana.com)
+ ([source](https://github.com/angeloocana/angeloocana))
* [knpw.rs](https://knpw.rs) ([source](https://github.com/knpwrs/knpw.rs))
-* [Overlap.show](https://overlap.show) ([source](https://github.com/pouretrebelle/overlap.show))
+* [Overlap.show](https://overlap.show)
+ ([source](https://github.com/pouretrebelle/overlap.show))
* [smartive Company Website](https://smartive.ch)
* [Haboba Find Jobs at Phu Quoc Island](http://haboba.com)
-* [Charlie Harrington's Blog](https://charlieharrington.com) ([source](https://github.com/whatrocks/blog))
-* [Song Wang’s website](https://songwang.io/) ([source](https://github.com/wangsongiam/songwang.io))
-* [Digital Psychology](http://digitalpsychology.io) ([source](https://github.com/danistefanovic/digitalpsychology.io))
-* [Magicly's blog](https://magicly.me/) ([source](https://github.com/magicly/gatsby-blog))
-* [Dalbinaco's website](http://dalbinaco.com/) ([source](https://github.com/dalbinaco/dalbinaco.github.io))
+* [Charlie Harrington's Blog](https://charlieharrington.com)
+ ([source](https://github.com/whatrocks/blog))
+* [Song Wang’s website](https://songwang.io/)
+ ([source](https://github.com/wangsongiam/songwang.io))
+* [Digital Psychology](http://digitalpsychology.io)
+ ([source](https://github.com/danistefanovic/digitalpsychology.io))
+* [Magicly's blog](https://magicly.me/)
+ ([source](https://github.com/magicly/gatsby-blog))
+* [Dalbinaco's website](http://dalbinaco.com/)
+ ([source](https://github.com/dalbinaco/dalbinaco.github.io))
* [Phu Quoc Works](http://phuquocworks.net)
-* [Kabir Goel's website](https://kbrgl.github.io) ([source](https://github.com/kbrgl/kbrgl.github.io))
-* [Gabriel Adorf's Portfolio](https://gabrieladorf.com/) ([source](https://github.com/gabdorf/gabriel-adorf-portfolio))
-* [CSS Grid Playground by MozillaDev](https://mozilladevelopers.github.io/playground/) ([source](https://github.com/MozillaDevelopers/playground))
-* [David James' Portfolio](http://dfjames.com) ([source](https://github.com/daviddeejjames/dfjames-gatsby))
-* [Tic Tac Toe AI](https://tic-tac-toe-ai.surge.sh) ([source](https://github.com/angeloocana/tic-tac-toe-ai))
-* [Etcetera Design](https://etcetera.design) ([source](https://github.com/etceteradesign/website))
+* [Kabir Goel's website](https://kbrgl.github.io)
+ ([source](https://github.com/kbrgl/kbrgl.github.io))
+* [Gabriel Adorf's Portfolio](https://gabrieladorf.com/)
+ ([source](https://github.com/gabdorf/gabriel-adorf-portfolio))
+* [CSS Grid Playground by MozillaDev](https://mozilladevelopers.github.io/playground/)
+ ([source](https://github.com/MozillaDevelopers/playground))
+* [David James' Portfolio](http://dfjames.com)
+ ([source](https://github.com/daviddeejjames/dfjames-gatsby))
+* [Tic Tac Toe AI](https://tic-tac-toe-ai.surge.sh)
+ ([source](https://github.com/angeloocana/tic-tac-toe-ai))
+* [Etcetera Design](https://etcetera.design)
+ ([source](https://github.com/etceteradesign/website))
* [Azer Koçulu](http://azer.bike)
* [Random Screencast](https://randomscreencast.com)
* [Phu Quoc Tea & Coffee Store](http://trasuaphuquoc.com)
* [Steven Natera's blog](https://www.stevennatera.com)
* [LekoArts - Graphic Designer](https://www.lekoarts.de)
-* [Georgi Yanev](https://blog.georgi-yanev.com) ([source](https://github.com/jumpalottahigh/blog.georgi-yanev.com))
+* [Georgi Yanev](https://blog.georgi-yanev.com)
+ ([source](https://github.com/jumpalottahigh/blog.georgi-yanev.com))
* [OnCallogy.com](https://www.oncallogy.com)
* [doopoll's marketing site](https://doopoll.co)
* [Design Systems Weekly](https://designsystems.email/)
@@ -70,15 +94,22 @@ Websites built with Gatsby:
* [JavaScript Stuff](https://www.javascriptstuff.com)
* [GRANDstack - GraphQL, React, Apollo, Neo4j Database](http://grandstack.io/)
* [GraphCMS's website](https://graphcms.com)
-* [Mannequin.io](https://mannequin.io) ([source](https://github.com/LastCallMedia/Mannequin/tree/master/site))
+* [Mannequin.io](https://mannequin.io)
+ ([source](https://github.com/LastCallMedia/Mannequin/tree/master/site))
* [Calpa's Blog](https://calpa.me) [(source)](https://github.com/calpa/blog)
-* [API Platform](https://api-platform.com) ([source](https://github.com/api-platform/website))
-* [Bottender Docs](https://bottender.js.org/) ([source](https://github.com/bottenderjs/bottenderjs.github.io))
-* [How to GraphQL](https://www.howtographql.com/) ([source](https://github.com/howtographql/howtographql))
-* [greglobinski.com](https://greglobinski.com) ([source](https://github.com/greglobinski/greglobinski-com))
+* [API Platform](https://api-platform.com)
+ ([source](https://github.com/api-platform/website))
+* [Bottender Docs](https://bottender.js.org/)
+ ([source](https://github.com/bottenderjs/bottenderjs.github.io))
+* [How to GraphQL](https://www.howtographql.com/)
+ ([source](https://github.com/howtographql/howtographql))
+* [greglobinski.com](https://greglobinski.com)
+ ([source](https://github.com/greglobinski/greglobinski-com))
* [Vibert Thio's Portfolio](https://vibertthio.com/portfolio/)([source](https://github.com/vibertthio/portfolio))
-* [hunterchang.com](https://hunterchang.com) ([source](https://github.com/ChangoMan/hc-gatsby))
-* [YouFoundRon.com](https://youfoundron.com) ([source](https://github.com/rongierlach/yfr-dot-com))
+* [hunterchang.com](https://hunterchang.com)
+ ([source](https://github.com/ChangoMan/hc-gatsby))
+* [YouFoundRon.com](https://youfoundron.com)
+ ([source](https://github.com/rongierlach/yfr-dot-com))
## Docs
@@ -90,15 +121,19 @@ Websites built with Gatsby:
## Packages
-This repository is a monorepo managed using [Lerna](https://github.com/lerna/lerna). This means that we publish [many packages](/packages) to NPM from the same codebase.
+This repository is a monorepo managed using
+[Lerna](https://github.com/lerna/lerna). This means that we publish
+[many packages](/packages) to NPM from the same codebase.
## Thanks
-Thanks to our many contributors and sponsors as well as the companies sponsoring our testing and hosting infrastructure, Travis CI, Appveyor, and Netlify.
+Thanks to our many contributors and sponsors as well as the companies sponsoring
+our testing and hosting infrastructure, Travis CI, Appveyor, and Netlify.
## Backers
-Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/gatsby#backer)]
+Support us with a monthly donation and help us continue our activities.
+[[Become a backer](https://opencollective.com/gatsby#backer)]
@@ -131,10 +166,10 @@ Support us with a monthly donation and help us continue our activities. [[Become
-
## Sponsors
-Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/gatsby#sponsor)]
+Become a sponsor and get your logo on our README on GitHub with a link to your
+site. [[Become a sponsor](https://opencollective.com/gatsby#sponsor)]
diff --git a/docs/README.md b/docs/README.md
index 047633ed18c9e..61e01bafb00cf 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,7 @@
# Read docs at https://www.gatsbyjs.org/docs
-We intend the docs to be read on gatsbyjs.org — you can read them here of course :-) just be warned that links won't often work and other things will be missing or less than optimal.
+We intend the docs to be read on gatsbyjs.org — you can read them here of course
+:-) just be warned that links won't often work and other things will be missing
+or less than optimal.
Go forth and build cool stuff.
diff --git a/docs/blog/2017-02-21-1-0-progress-update-where-came-from-where-going/index.md b/docs/blog/2017-02-21-1-0-progress-update-where-came-from-where-going/index.md
index 8c66d48baf580..80b183694e363 100644
--- a/docs/blog/2017-02-21-1-0-progress-update-where-came-from-where-going/index.md
+++ b/docs/blog/2017-02-21-1-0-progress-update-where-came-from-where-going/index.md
@@ -5,55 +5,53 @@ author: "Kyle Mathews"
image: 'ui-and-code.png'
draft: true
---
-Imagine for a moment the perfect website framework. One that produced
-really fast sites by default, that let you use the latest web tools and
-browser features without complicated setup, and that helped your team
-stay coordinated as you develop, ship, and maintain sites.
+
+Imagine for a moment the perfect website framework. One that produced really
+fast sites by default, that let you use the latest web tools and browser
+features without complicated setup, and that helped your team stay coordinated
+as you develop, ship, and maintain sites.
This framework would have to be:
-* **universal**, work for all types of sites from simple brocurewares to
-complex web-apps.
-* **simple**, not requiring any setup to start using and with thoughtful
-APIs to extend the framework.
+* **universal**, work for all types of sites from simple brocurewares to complex
+ web-apps.
+* **simple**, not requiring any setup to start using and with thoughtful APIs to
+ extend the framework.
* **fast**, doesn't lose customers to slow page loads. Takes advantage of
-HTTP/2, browser caching, service workers, inlined critical css, and code
-splitting so your site always loads incredibly fast—no matter what you
-build.
-* **JavaScript-driven**, the web is huge and intensely competitive.
-Sites that win are fast and richly interactive. Your framework must make
-it trivial to use advanced JavaScript.
-* **team ready**, use industry standard collaboration tools like NPM,
-Git, and continuous deployment, so your team is always on the same page
-and shipping new features is easy.
-* **modular**, allows for cleanly separated features so fixing bugs and
-adding new features is easy and complexity is contained.
-* **internet scale**, launch your site to millions without crashing your
-site (or your wallet).
+ HTTP/2, browser caching, service workers, inlined critical css, and code
+ splitting so your site always loads incredibly fast—no matter what you build.
+* **JavaScript-driven**, the web is huge and intensely competitive. Sites that
+ win are fast and richly interactive. Your framework must make it trivial to
+ use advanced JavaScript.
+* **team ready**, use industry standard collaboration tools like NPM, Git, and
+ continuous deployment, so your team is always on the same page and shipping
+ new features is easy.
+* **modular**, allows for cleanly separated features so fixing bugs and adding
+ new features is easy and complexity is contained.
+* **internet scale**, launch your site to millions without crashing your site
+ (or your wallet).
* **secure**, doesn't put your your users' data at risk of hacking.
-I believe that Gatsby fulfills these requirements. After several years
-of working on the project and seeing it used successfully by many people
-on a wide variety of sites, I'm confident that Gatsby works.
+I believe that Gatsby fulfills these requirements. After several years of
+working on the project and seeing it used successfully by many people on a wide
+variety of sites, I'm confident that Gatsby works.
-Since I open sourced Gatsby in 2015, it's collected over **8000 stars**
-on GitHub (by far the most stars on GitHub for a project of its type),
-been joined by **122 contributors**, and **downloaded 130,000** times!
+Since I open sourced Gatsby in 2015, it's collected over **8000 stars** on
+GitHub (by far the most stars on GitHub for a project of its type), been joined
+by **122 contributors**, and **downloaded 130,000** times!
-In mid-2016, I decided to [work full-time on
-Gatsby](https://www.bricolage.io/gatsby-open-source-work/) and started
-researching and prototyping ideas that are now coming together as Gatsby
-1.0.
+In mid-2016, I decided to
+[work full-time on Gatsby](https://www.bricolage.io/gatsby-open-source-work/)
+and started researching and prototyping ideas that are now coming together as
+Gatsby 1.0.
## What is Gatsby
-Gatsby combines the fast performance of static websites with the
-powerful abstractions, excellent tools, and client capabilities of
-the web-app world.
+Gatsby combines the fast performance of static websites with the powerful
+abstractions, excellent tools, and client capabilities of the web-app world.
-It is a general purpose data-centric web framework that is [successfully
-being used for a wide variety of
-sites](https://github.com/gatsbyjs/gatsby#sites-built-with-gatsby)
+It is a general purpose data-centric web framework that is
+[successfully being used for a wide variety of sites](https://github.com/gatsbyjs/gatsby#sites-built-with-gatsby)
including blogs, marketing sites, documentation sites, and e-commerce.
It wraps three of the most popular web app tools into a cohesive website
@@ -63,109 +61,103 @@ framework:
* [Webpack](https://webpack.js.org/) for bundling JavaScript and CSS
* [GraphQL](http://graphql.org/) from Facebook for declarative data queries
-While designing Gatsby, I wanted a synthesis of two of my favorite
-developer experiences. The simplicity of building sites with markdown
-and static site generators and the powerful hot-reloading environment of
-the React world.
+While designing Gatsby, I wanted a synthesis of two of my favorite developer
+experiences. The simplicity of building sites with markdown and static site
+generators and the powerful hot-reloading environment of the React world.
![Gatsby development
experience](https://camo.githubusercontent.com/0506699aaaae2f9772cc381b92f2aa5e14eba296/687474703a2f2f7a697070792e6766796361742e636f6d2f556c74696d6174655765656b6c7942617265626972646261742e676966)
-When loading a page in a Gatsby site, browsers first load the page's
-pre-built HTML file and then load the minimum JavaScript needed to make
-that page interactive.
+When loading a page in a Gatsby site, browsers first load the page's pre-built
+HTML file and then load the minimum JavaScript needed to make that page
+interactive.
-Because Gatsby sites are just static files, you're ensured a much more
-*carefree deployment*. There are no *complicated databases* to install
-and maintain and *web-servers to scale* and protect against hacking.
+Because Gatsby sites are just static files, you're ensured a much more _carefree
+deployment_. There are no _complicated databases_ to install and maintain and
+_web-servers to scale_ and protect against hacking.
-Serving static files ensures consistent *super fast load times*. Once
-your site is loaded, Gatsby automatically *pre-fetches* adjacent pages.
-This means navigating around your site feels *instantaneous* as all the
-content and scripts for the next page has been loaded already. Since
-you're reading this on a Gatsby site, try clicking on a link in the
-header and then click back (note, this site is still being worked on as we
-approach 1.0). A bit faster than your current site no? 😜
+Serving static files ensures consistent _super fast load times_. Once your site
+is loaded, Gatsby automatically _pre-fetches_ adjacent pages. This means
+navigating around your site feels _instantaneous_ as all the content and scripts
+for the next page has been loaded already. Since you're reading this on a Gatsby
+site, try clicking on a link in the header and then click back (note, this site
+is still being worked on as we approach 1.0). A bit faster than your current
+site no? 😜
## Apps vs sites
-From nearly the beginning of the web, the idea of the web as an
-application platform has competed with the idea of the web as a series
-of "documents".
+From nearly the beginning of the web, the idea of the web as an application
+platform has competed with the idea of the web as a series of "documents".
-In recent years, the "app" paradigm has gained steam as dozens of
-JavaScript frameworks and other JavaScript tools have been released,
-exploring ideas and competing for mind-share.
+In recent years, the "app" paradigm has gained steam as dozens of JavaScript
+frameworks and other JavaScript tools have been released, exploring ideas and
+competing for mind-share.
-100s of millions of dollars have been invested by the largest companies
-in the world in these JavaScript frameworks and the larger ecosystem of
-tools surrounding them.
+100s of millions of dollars have been invested by the largest companies in the
+world in these JavaScript frameworks and the larger ecosystem of tools
+surrounding them.
-The improvement has been dramatic and exhilarating. I can remember many
-things I struggled for weeks to build in ~2010-2013 that took me days or
-even hours once I'd adopted React.
+The improvement has been dramatic and exhilarating. I can remember many things I
+struggled for weeks to build in ~2010-2013 that took me days or even hours once
+I'd adopted React.
-React has taken over the web world and for good reason. Its three big
-ideas, composable components, lifecycle APIs, and one-way data flow
-dramatically *simplify* web UI development. Things that are really hard
-to build within other paradigms feel almost easy with React.
+React has taken over the web world and for good reason. Its three big ideas,
+composable components, lifecycle APIs, and one-way data flow dramatically
+_simplify_ web UI development. Things that are really hard to build within other
+paradigms feel almost easy with React.
## Time for a JavaScript web framework?
-The internet runs on Open Source CMSs—primarily Wordpress and Drupal. I
-spent most of college building Drupal websites and writing [open-source
-Drupal
-modules](https://www.bricolage.io/first-beta-release-drupal-native-mailinglist-module/).
-My first startup job was at [Pantheon](https://pantheon.io)—where I
-helped [design and build developer tools](https://www.bricolage.io/new-beginnings/)
-for teams building Drupal & Wordpress sites.
+The internet runs on Open Source CMSs—primarily Wordpress and Drupal. I spent
+most of college building Drupal websites and writing
+[open-source Drupal modules](https://www.bricolage.io/first-beta-release-drupal-native-mailinglist-module/).
+My first startup job was at [Pantheon](https://pantheon.io)—where I helped
+[design and build developer tools](https://www.bricolage.io/new-beginnings/) for
+teams building Drupal & Wordpress sites.
-These open source CMSs are *extraordinary tools and have remarkably dynamic
-ecosystems*. They truly run the web. Wordpress alone runs more than 25%
-of all websites on the internet!
+These open source CMSs are _extraordinary tools and have remarkably dynamic
+ecosystems_. They truly run the web. Wordpress alone runs more than 25% of all
+websites on the internet!
But still, the time seems ripe for a client-centric web framework.
-As more and more sites are expected to become app-like there's been a
-*rush to add more JavaScript into our sites* resulting in an explosion of
-tool complexity resulting in, at times, poorly optimized sites that ship
-far too much JavaScript at the wrong times bogging down the site.
+As more and more sites are expected to become app-like there's been a _rush to
+add more JavaScript into our sites_ resulting in an explosion of tool complexity
+resulting in, at times, poorly optimized sites that ship far too much JavaScript
+at the wrong times bogging down the site.
-But it doesn't need to be this way. We use web frameworks because they
-*embed smart ideas about how to organize our code* so we're guided towards
-building fast sites that are simple to build and maintain.
+But it doesn't need to be this way. We use web frameworks because they _embed
+smart ideas about how to organize our code_ so we're guided towards building
+fast sites that are simple to build and maintain.
-Gatsby aims to be a *modern web framework* that's designed with the
-assumption that you need a rich client. Gatsby bakes in modern
-JavaScript compiler and bundling tools along with a full asset pipeline
-so you can just start writing your website and *be confident things will
-work*.
+Gatsby aims to be a _modern web framework_ that's designed with the assumption
+that you need a rich client. Gatsby bakes in modern JavaScript compiler and
+bundling tools along with a full asset pipeline so you can just start writing
+your website and _be confident things will work_.
## Gatsby 1.0: Setting the foundation for a modern JavaScript website framework
-I started working on the [1.0
-branch](https://github.com/gatsbyjs/gatsby/tree/1.0) in August and after
+I started working on the
+[1.0 branch](https://github.com/gatsbyjs/gatsby/tree/1.0) in August and after
months of hard work, our first beta release is in sight.
The changes for 1.0 can be organized into a few areas.
### Add service worker and offline support
-Service workers are perhaps the most exciting technology that's come to
-the web in the past several years. It makes possible (finally!)
-sophisticated client caching plus true offline support. I've added
-excellent on-by-default support to Gatsby for Service Workers and a
-great offline experience. If you're using Chrome or Firefox, this site
-loads offline! *Service workers make your site much more resilient
-against bad networks*. If someone loads your site on a train and goes
-through a tunnel, you won't lose them as they'll still be able to keep
+Service workers are perhaps the most exciting technology that's come to the web
+in the past several years. It makes possible (finally!) sophisticated client
+caching plus true offline support. I've added excellent on-by-default support to
+Gatsby for Service Workers and a great offline experience. If you're using
+Chrome or Firefox, this site loads offline! _Service workers make your site much
+more resilient against bad networks_. If someone loads your site on a train and
+goes through a tunnel, you won't lose them as they'll still be able to keep
clicking around.
### Route-based code splitting
-Many sites generate one JavaScript bundle for the *entire* site. Which
-means someone loading your frontpage loads far more code than is
-necessary.
+Many sites generate one JavaScript bundle for the _entire_ site. Which means
+someone loading your frontpage loads far more code than is necessary.
Gatsby 1.0 only loads the scripts necessary for the page you're on. As you
navigate around, Gatsby loads the JavaScript needed for each route.
@@ -179,67 +171,63 @@ import threejs from "react-threejs"
...won't affect the performance of the rest of the site.
-This is particularly helpful for teams of people collaborating on a site
-with pages with very different technical and business requirements.
-Different parts of the site can evolve independently of each other.
+This is particularly helpful for teams of people collaborating on a site with
+pages with very different technical and business requirements. Different parts
+of the site can evolve independently of each other.
-One client I'm working with on Gatsby 1.0 (a stealth startup in San
-Francisco) is using Gatsby to build both their marketing site *and* SaaS
-app within the *same Gatsby codebase*.
+One client I'm working with on Gatsby 1.0 (a stealth startup in San Francisco)
+is using Gatsby to build both their marketing site _and_ SaaS app within the
+_same Gatsby codebase_.
-The marketing pages of their site are built using markdown and React
-components along with a modern css-in-js library
-[Glamor](https://github.com/threepointone/glamor) for styling.
-The SaaS portion uses [Redux](http://redux.js.org/) to communicate with
-their Django API.
+The marketing pages of their site are built using markdown and React components
+along with a modern css-in-js library
+[Glamor](https://github.com/threepointone/glamor) for styling. The SaaS portion
+uses [Redux](http://redux.js.org/) to communicate with their Django API.
-The marketing portion of the site loads quickly with minimal JavaScript.
-When a potential customer goes to sign-up for the app, there's no
-*awkward jump from the marketing website to the web app*—just a simple
-page change which seamlessly loads in the needed JavaScript. The *team
-is sharing components and styles across the site* without stepping on
-each others shoes as they rapidly iterate on features.
+The marketing portion of the site loads quickly with minimal JavaScript. When a
+potential customer goes to sign-up for the app, there's no *awkward jump from
+the marketing website to the web app*—just a simple page change which seamlessly
+loads in the needed JavaScript. The _team is sharing components and styles
+across the site_ without stepping on each others shoes as they rapidly iterate
+on features.
### Plugin and Theme systems
-Wordpress & Jekyll are both great examples of open source communities
-with robust theme & plugins ecosystems.
+Wordpress & Jekyll are both great examples of open source communities with
+robust theme & plugins ecosystems.
-Themes and plugins help accelerate building as you can build on what
-others have done and help collaborate with others on basic building
-blocks
+Themes and plugins help accelerate building as you can build on what others have
+done and help collaborate with others on basic building blocks
Gatsby 1.0 will be adding plugin and theme support.
-The plugin system will let you hook into lifecycle APIs from events
-during the bootstrap and build processes and in the browser.
+The plugin system will let you hook into lifecycle APIs from events during the
+bootstrap and build processes and in the browser.
There are a [number of official Gatsby plugins](/docs/plugins/) already
-built—all distributed as separate NPM packages. It'll be easy to create
-your own plugins for internal projects and as open source projects
-published on NPM.
+built—all distributed as separate NPM packages. It'll be easy to create your own
+plugins for internal projects and as open source projects published on NPM.
Plugins can:
* add support for webpack loaders such as Sass, Less
* add drop-in support for lightweight React-compatible frameworks
-[Preact](https://preactjs.com/) and [Inferno](https://infernojs.org/)
+ [Preact](https://preactjs.com/) and [Inferno](https://infernojs.org/)
* add a sitemap or RSS feed
* add [Google Analytics](/packages/gatsby-plugin-google-analytics/)
* ...and many more!
Plugins also drive the new GraphQL data processing layer.
-The final pieces for theme support are coming soon. Gatsby's theme system
-will have some unique properties. You'll be able to add multiple themes
-to a site. So you could start a site with a "blog" theme and later add
-on a "portfolio" theme. Themes will also be able to *compose* other
-themes. So a large organization could have a standard "base" theme and
-then individual departments could extend the base theme to meet their
-specific requirements.
+The final pieces for theme support are coming soon. Gatsby's theme system will
+have some unique properties. You'll be able to add multiple themes to a site. So
+you could start a site with a "blog" theme and later add on a "portfolio" theme.
+Themes will also be able to _compose_ other themes. So a large organization
+could have a standard "base" theme and then individual departments could extend
+the base theme to meet their specific requirements.
-Themes (like plugins) will be published on NPM. So soon, starting a new
-Gatsby blog will be as simple as:
+Themes (like plugins) will be published on NPM. So soon, starting a new Gatsby
+blog will be as simple as:
```bash
npm install --save gatsby-super-cool-theme
@@ -248,36 +236,32 @@ gatsby build --theme gatsby-super-cool-theme
### GraphQL data layer
-Currently data in Gatsby (like pretty much every static site generator)
-is processed then *pushed* into templates to be rendered into HTML. This
-is a simple pattern and works great for many use cases. But when you
-start working on more complex sites, you really start to miss the
-flexibility of building a database-driven site. With a database, all
-your data is available to query against in any fashion you'd like.
-Whatever bits of data you need to assemble a page, you can *pull* in.
-You want to create author pages showing their bio and last 5 posts? It's
-just a query away.
-
-I wanted this same flexibility for Gatsby. So for 1.0, I've built a new
-data processing layer which converts your static data files (or any
-other data source) into a *GraphQL schema* which you can query against
-like a database.
-
-Every Gatsby page or page template can have a GraphQL query which tells
-Gatsby what data is required for that page. The data layer runs the
-GraphQL queries during development and at build time and writes out a
-JSON file with the result of the query. This JSON file is then injected
-into the React component as props.
-
-Because we know at build-time what data is needed for every page, we can
-easily pre-fetch page data meaning even very complex, data-heavy pages
-load almost instantly.
-
-This pattern of *colocating* your queries next to your views is copied
-from the [Relay data framework from
-Facebook](https://facebook.github.io/relay/). Colocaton makes it easy to
-fully understand your views as everything necessary for that view
-is fully described there.
+Currently data in Gatsby (like pretty much every static site generator) is
+processed then _pushed_ into templates to be rendered into HTML. This is a
+simple pattern and works great for many use cases. But when you start working on
+more complex sites, you really start to miss the flexibility of building a
+database-driven site. With a database, all your data is available to query
+against in any fashion you'd like. Whatever bits of data you need to assemble a
+page, you can _pull_ in. You want to create author pages showing their bio and
+last 5 posts? It's just a query away.
+
+I wanted this same flexibility for Gatsby. So for 1.0, I've built a new data
+processing layer which converts your static data files (or any other data
+source) into a _GraphQL schema_ which you can query against like a database.
+
+Every Gatsby page or page template can have a GraphQL query which tells Gatsby
+what data is required for that page. The data layer runs the GraphQL queries
+during development and at build time and writes out a JSON file with the result
+of the query. This JSON file is then injected into the React component as props.
+
+Because we know at build-time what data is needed for every page, we can easily
+pre-fetch page data meaning even very complex, data-heavy pages load almost
+instantly.
+
+This pattern of _colocating_ your queries next to your views is copied from the
+[Relay data framework from Facebook](https://facebook.github.io/relay/).
+Colocaton makes it easy to fully understand your views as everything necessary
+for that view is fully described there.
A simple example of how this works in practice.
@@ -292,17 +276,16 @@ date: "2017-02-23"
This is my sweet blog post. **Cool!**
```
-In our site, we would write a React component which acts as a template
-for all the blog posts. Included with the component is an exported
-`pageQuery`.
+In our site, we would write a React component which acts as a template for all
+the blog posts. Included with the component is an exported `pageQuery`.
```javascript
// A simple React component for rendering a blog page.
import React from "react"
class BlogPostTemplate extends React.Component {
- render () {
-
+ render() {
+ ;
{this.props.data.markdown.frontmatter.title}
{this.props.data.markdown.frontmatter.date}
{post.frontmatter.title}
-
+
- );
+ )
}
```
-Whoa, neat! This React component will be rendered to a static HTML string (for each route/blog post we define), which will serve as the basis of our routing/navigation for our blog.
+Whoa, neat! This React component will be rendered to a static HTML string (for
+each route/blog post we define), which will serve as the basis of our
+routing/navigation for our blog.
-At this point, there is a reasonable level of confusion and "magic" occuring, particularly with the props injection. What is `markdownRemark`? Where is this `data` prop injected from? All good questions, so let's answer them by writing a GraphQL query to seed our `
` component with content!
+At this point, there is a reasonable level of confusion and "magic" occuring,
+particularly with the props injection. What is `markdownRemark`? Where is this
+`data` prop injected from? All good questions, so let's answer them by writing a
+GraphQL query to seed our `
` component with content!
### Writing the GraphQL query
-Below the `Template` declaration, we'll want to add a GraphQL query. This is an incredibly powerful utility provided by Gatsby which lets us pick and choose very simply the pieces of data that we want to display for our blog post. Each piece of data our query selects will be injected via the `data` property we specified earlier.
+Below the `Template` declaration, we'll want to add a GraphQL query. This is an
+incredibly powerful utility provided by Gatsby which lets us pick and choose
+very simply the pieces of data that we want to display for our blog post. Each
+piece of data our query selects will be injected via the `data` property we
+specified earlier.
```javascript{21-32}
import React from 'react';
@@ -233,35 +333,70 @@ export const pageQuery = graphql`
`;
```
-If you're not familar with GraphQL, this may seem slightly confusing, but we can break down what's going down here piece by piece.
-
-*Note: To learn more about GraphQL, consider this [excellent resource][learn-graphql]*
-
-The underlying query name `BlogPostByPath` (note: these query names need to be unique!) will be injected with the current path, e.g. the specific blog post we are viewing. This path will be available as `$path` in our query. For instance, if we were viewing our previously created blog post, the path of the file that data will be pulled from will be `/hello-world`.
-
-`markdownRemark` will be the injected property available via the prop `data`, as named in the GraphQL query. Each property we pull via the GraphQL query will be available under this `markdownRemark` property. For example, to access the transformed HTML we would access the `data` prop via `data.markdownRemark.html`.
-
-`frontmatter`, is of course our data structure we provided at the beginning of our Markdown file. Each key we define there will be available to be injected into the query.
-
-At this point, we have a bunch of plugins installed to load files off of disk, transform Markdown to HTML, and other utilities. We have a single, lonely Markdown file that will be rendered as a blog post. Finally, we have a React template for blog posts, as well as a wired up GraphQL query to query for a blog post and inject the React template with the queried data. Next up: programmatically creating the necessary static pages (and injecting the templates) with Gatsby's Node API. Let's get down to it.
-
-An important note to make at this point is that the GraphQL query takes place at **build** time. The component is injected with the `data` prop that is seeded by the GraphQL query. Unless anything dynamic (e.g. logic in `componentDidMount`, state changes, etc.) occurs, this component will be pure, rendered HTML generated via the React rendering engine, GraphQL, and Gatsby!
+If you're not familar with GraphQL, this may seem slightly confusing, but we can
+break down what's going down here piece by piece.
+
+_Note: To learn more about GraphQL, consider this [excellent
+resource][learn-graphql]_
+
+The underlying query name `BlogPostByPath` (note: these query names need to be
+unique!) will be injected with the current path, e.g. the specific blog post we
+are viewing. This path will be available as `$path` in our query. For instance,
+if we were viewing our previously created blog post, the path of the file that
+data will be pulled from will be `/hello-world`.
+
+`markdownRemark` will be the injected property available via the prop `data`, as
+named in the GraphQL query. Each property we pull via the GraphQL query will be
+available under this `markdownRemark` property. For example, to access the
+transformed HTML we would access the `data` prop via `data.markdownRemark.html`.
+
+`frontmatter`, is of course our data structure we provided at the beginning of
+our Markdown file. Each key we define there will be available to be injected
+into the query.
+
+At this point, we have a bunch of plugins installed to load files off of disk,
+transform Markdown to HTML, and other utilities. We have a single, lonely
+Markdown file that will be rendered as a blog post. Finally, we have a React
+template for blog posts, as well as a wired up GraphQL query to query for a blog
+post and inject the React template with the queried data. Next up:
+programmatically creating the necessary static pages (and injecting the
+templates) with Gatsby's Node API. Let's get down to it.
+
+An important note to make at this point is that the GraphQL query takes place at
+**build** time. The component is injected with the `data` prop that is seeded by
+the GraphQL query. Unless anything dynamic (e.g. logic in `componentDidMount`,
+state changes, etc.) occurs, this component will be pure, rendered HTML
+generated via the React rendering engine, GraphQL, and Gatsby!
## Creating the static pages
-Gatsby exposes a powerful Node API, which allows for functionality such as creating dynamic pages (blog posts!), extending the babel or webpack configs, modifying the created nodes or pages, etc. This API is exposed in the `gatsby-node.js` file in the root directory of your project—e.g. at the same level as `gatsby-config.js`. Each export found in this file will be parsed by Gatsby, as detailed in its [Node API specification][node-spec]. However, we only care about one particular API in this instance, `createPages`.
+Gatsby exposes a powerful Node API, which allows for functionality such as
+creating dynamic pages (blog posts!), extending the babel or webpack configs,
+modifying the created nodes or pages, etc. This API is exposed in the
+`gatsby-node.js` file in the root directory of your project—e.g. at the same
+level as `gatsby-config.js`. Each export found in this file will be parsed by
+Gatsby, as detailed in its [Node API specification][node-spec]. However, we only
+care about one particular API in this instance, `createPages`.
```javascript
-const path = require('path');
+const path = require("path")
exports.createPages = ({ boundActionCreators, graphql }) => {
- const { createPage } = boundActionCreators;
+ const { createPage } = boundActionCreators
- const blogPostTemplate = path.resolve(`src/templates/blog-post.js`);
+ const blogPostTemplate = path.resolve(`src/templates/blog-post.js`)
}
```
-Nothing super complex yet! We're using the `createPages` API (which Gatsby will call at build time with injected parameters). We're also grabbing the _path_ to our blogPostTemplate we created earlier. Finally, we're using the `createPage` action creator/function made available in boundActionCreators. Gatsby uses Redux internally to manage its state, and `boundActionCreators` are simply the exposed action creators of Gatsby, of which `createPage` is one of the action creators! For the full list of exposed action creators, check out [Gatsby's documentation][gatsby-bound-action-creators]. We can now construct the GraphQL query, which will fetch all of our Markdown posts.
+Nothing super complex yet! We're using the `createPages` API (which Gatsby will
+call at build time with injected parameters). We're also grabbing the _path_ to
+our blogPostTemplate we created earlier. Finally, we're using the `createPage`
+action creator/function made available in boundActionCreators. Gatsby uses Redux
+internally to manage its state, and `boundActionCreators` are simply the exposed
+action creators of Gatsby, of which `createPage` is one of the action creators!
+For the full list of exposed action creators, check out [Gatsby's
+documentation][gatsby-bound-action-creators]. We can now construct the GraphQL
+query, which will fetch all of our Markdown posts.
### Querying for posts
@@ -300,11 +435,21 @@ exports.createPages = ({ boundActionCreators, graphql }) => {
}
```
-We're using GraphQL to get all Markdown nodes and making them available under the `allMarkdownRemark` GraphQL property. Each exposed property (on `node`) is made available for querying against. We're effectively seeding a GraphQL "database" that we can then query against via page-level GraphQL queries. One note here is that the `exports.createPages` API expects a Promise to be returned, so it works seamlessly with the `graphql` function, which returns a Promise (although note a callback API is also available if that's more your thing).
+We're using GraphQL to get all Markdown nodes and making them available under
+the `allMarkdownRemark` GraphQL property. Each exposed property (on `node`) is
+made available for querying against. We're effectively seeding a GraphQL
+"database" that we can then query against via page-level GraphQL queries. One
+note here is that the `exports.createPages` API expects a Promise to be
+returned, so it works seamlessly with the `graphql` function, which returns a
+Promise (although note a callback API is also available if that's more your
+thing).
-One cool note here is that the `gatsby-plugin-remark` plugin exposes some useful data for us to query with GraphQL, e.g. `excerpt` (a short snippet to display as a preview), `id` (a unique identifier for each post), etc.
+One cool note here is that the `gatsby-plugin-remark` plugin exposes some useful
+data for us to query with GraphQL, e.g. `excerpt` (a short snippet to display as
+a preview), `id` (a unique identifier for each post), etc.
-We now have our query written, but we haven't yet programmatically created the pages (with the `createPage` action creator). Let's do that!
+We now have our query written, but we haven't yet programmatically created the
+pages (with the `createPage` action creator). Let's do that!
### Creating the pages
@@ -352,33 +497,60 @@ exports.createPages = ({ boundActionCreators, graphql }) => {
}
```
-We've now tied into the Promise chain exposed by the `graphql` query. The actual posts are available via the path `result.data.allMarkdownRemark.edges`. Each edge contains an internal node, and this node holds the useful data that we will use to construct a page with Gatsby. Our GraphQL "shape" is directly reflected in this data object, so each property we pulled from that query will be available when we are querying in our GraphQL blog post template.
-
-The `createPage` API accepts an object which requires `path` and `component` properties to be defined, which we have done above. Additionally, an optional property `context` can be used to inject data and make it available to the blog post template component via injected props (log out props to see each available prop!). Each time we build with Gatsby, `createPage` will be called, and Gatsby will create a static HTML file of the path we specified in the post's frontmatter--the result of which will be our stringified and parsed React template injected with the data from our GraphQL query. Whoa, it's actually starting to come together!
-
-We can run `yarn develop` at this point, and then navigate to `http://localhost:8000/hello-world` to see our first blog post, which should look something like below:
+We've now tied into the Promise chain exposed by the `graphql` query. The actual
+posts are available via the path `result.data.allMarkdownRemark.edges`. Each
+edge contains an internal node, and this node holds the useful data that we will
+use to construct a page with Gatsby. Our GraphQL "shape" is directly reflected
+in this data object, so each property we pulled from that query will be
+available when we are querying in our GraphQL blog post template.
+
+The `createPage` API accepts an object which requires `path` and `component`
+properties to be defined, which we have done above. Additionally, an optional
+property `context` can be used to inject data and make it available to the blog
+post template component via injected props (log out props to see each available
+prop!). Each time we build with Gatsby, `createPage` will be called, and Gatsby
+will create a static HTML file of the path we specified in the post's
+frontmatter--the result of which will be our stringified and parsed React
+template injected with the data from our GraphQL query. Whoa, it's actually
+starting to come together!
+
+We can run `yarn develop` at this point, and then navigate to
+`http://localhost:8000/hello-world` to see our first blog post, which should
+look something like below:
![My first blog post with Gatsby](./my-first-blog-post.png)
-At this point, we've created a single static blog post as an HTML file, which was created by a React component and several GraphQL queries. However, this isn't a blog! We can't expect our users to guess the path of each post, we need to have an index or listing page, where we display each blog post, a short snippet, and a link to the full blog post. Wouldn't you know it, we can do this incredibly easily with Gatsby, using a similar strategy as we used in our blog template, e.g. a React component and a GraphQL query.
+At this point, we've created a single static blog post as an HTML file, which
+was created by a React component and several GraphQL queries. However, this
+isn't a blog! We can't expect our users to guess the path of each post, we need
+to have an index or listing page, where we display each blog post, a short
+snippet, and a link to the full blog post. Wouldn't you know it, we can do this
+incredibly easily with Gatsby, using a similar strategy as we used in our blog
+template, e.g. a React component and a GraphQL query.
## Creating the Blog Listing
-I won't go into quite as much detail for this section, because we've already done something very similar for our blog template! Look at us, we're pro Gatsby-ers at this point!
+I won't go into quite as much detail for this section, because we've already
+done something very similar for our blog template! Look at us, we're pro
+Gatsby-ers at this point!
-Gatsby has a standard for "listing pages," and they're placed in the root of our filesystem we specified in `gatsby-source-filesystem`, e.g. `src/pages/index.js`. So create that file if it does not exist, and let's get it working! Additionally note that any static JavaScript files (that export a React component!) will get a corresponding static HTML file. For instance, if we create `src/pages/tags.js`, the path `http://localhost:8000/tags/` will be available within the browser and the statically generated site.
+Gatsby has a standard for "listing pages," and they're placed in the root of our
+filesystem we specified in `gatsby-source-filesystem`, e.g.
+`src/pages/index.js`. So create that file if it does not exist, and let's get it
+working! Additionally note that any static JavaScript files (that export a React
+component!) will get a corresponding static HTML file. For instance, if we
+create `src/pages/tags.js`, the path `http://localhost:8000/tags/` will be
+available within the browser and the statically generated site.
```javascript
-import React from 'react';
-import Link from 'gatsby-link';
-import Helmet from 'react-helmet';
+import React from "react"
+import Link from "gatsby-link"
+import Helmet from "react-helmet"
// import '../css/index.css'; // add some style if you want!
-export default function Index({
- data
-}) {
- const { edges: posts } = data.allMarkdownRemark;
+export default function Index({ data }) {
+ const { edges: posts } = data.allMarkdownRemark
return (
{posts
@@ -392,10 +564,10 @@ export default function Index({
{post.frontmatter.date}
{post.excerpt}
- );
+ )
})}
- );
+ )
}
export const pageQuery = graphql`
@@ -414,24 +586,49 @@ export const pageQuery = graphql`
}
}
}
-`;
+`
```
-OK! So we've followed a similar approach to our blog post template, so this should hopefully seem pretty familiar. Once more we're exporting `pageQuery` which contains a GraphQL query. Note that we're pulling a slightly different data set, specifically we are pulling an `excerpt` of 250 characters rather than the full HTML, as well as we are formatting the pulled date with a format string! GraphQL is awesome.
-
-The actual React component is fairly trivial, but one important note should be made. It's important that when linking to internal content, i.e. other blog links, that you should always use `gatsby-link`. Gatsby does not work if pages are not routed via this utility. Additionally, this utility also works with `pathPrefix`, which allows for a Gatsby site to be deployed a non-root domain. This is useful if this blog will be hosted on something like GitHub Pages, or perhaps hosted at `/blog`.
-
-Now this is getting exciting and it feels like we're finally getting somewhere! At this point, we have a fully functional blog generated by Gatsby, with real content authored in Markdown, a blog listing, and the ability to navigate around in the blog. If you run `yarn develop`, `http://localhost:8000` should display a preview of each blog post, and each post title links to the content of the blog post. A real blog!
+OK! So we've followed a similar approach to our blog post template, so this
+should hopefully seem pretty familiar. Once more we're exporting `pageQuery`
+which contains a GraphQL query. Note that we're pulling a slightly different
+data set, specifically we are pulling an `excerpt` of 250 characters rather than
+the full HTML, as well as we are formatting the pulled date with a format
+string! GraphQL is awesome.
+
+The actual React component is fairly trivial, but one important note should be
+made. It's important that when linking to internal content, i.e. other blog
+links, that you should always use `gatsby-link`. Gatsby does not work if pages
+are not routed via this utility. Additionally, this utility also works with
+`pathPrefix`, which allows for a Gatsby site to be deployed a non-root domain.
+This is useful if this blog will be hosted on something like GitHub Pages, or
+perhaps hosted at `/blog`.
+
+Now this is getting exciting and it feels like we're finally getting somewhere!
+At this point, we have a fully functional blog generated by Gatsby, with real
+content authored in Markdown, a blog listing, and the ability to navigate around
+in the blog. If you run `yarn develop`, `http://localhost:8000` should display a
+preview of each blog post, and each post title links to the content of the blog
+post. A real blog!
![Blog listing](./blog-listing.png)
-It's now on you to make something incredible with the knowledge you've gained in following along with this tutorial! You can not only make it pretty and style with CSS (or [styled-components][styled-components]!), but you could improve it functionally by implementing some of the following:
+It's now on you to make something incredible with the knowledge you've gained in
+following along with this tutorial! You can not only make it pretty and style
+with CSS (or [styled-components][styled-components]!), but you could improve it
+functionally by implementing some of the following:
-- Add a tag listing and tag search page
- - hint: the `createPages` API in `gatsby-node.js` file is useful here, as is frontmatter
-- adding navigation between a specific blog post and past/present blog posts (the `context` API of `createPages` is useful here), etc.
+* Add a tag listing and tag search page
+ * hint: the `createPages` API in `gatsby-node.js` file is useful here, as is
+ frontmatter
+* adding navigation between a specific blog post and past/present blog posts
+ (the `context` API of `createPages` is useful here), etc.
-With our new found knowledge of Gatsby and its API, you should feel empowered to begin to utilize Gatsby to its fullest potential. A blog is just the starting point; Gatsby's rich ecosystem, extensible API, and advanced querying capabilities provide a powerful toolset for building truly incredible, performant sites.
+With our new found knowledge of Gatsby and its API, you should feel empowered to
+begin to utilize Gatsby to its fullest potential. A blog is just the starting
+point; Gatsby's rich ecosystem, extensible API, and advanced querying
+capabilities provide a powerful toolset for building truly incredible,
+performant sites.
Now go build something great.
@@ -439,37 +636,32 @@ Now go build something great.
## Links
-- [`@dschau/gatsby-blog-starter-kit`][source-code]
- - A working repo demonstrating all of the aforementioned functionality of Gatsby
-- [`@dschau/create-gatsby-blog-post`][create-gatsby-blog-post]
- - A utility and CLI I created to scaffold out a blog post following the predefined Gatsby structure with frontmatter, date, path, etc.
-- [Source code for my blog][blog-source-code]
- - The source code for my blog, which takes the gatsby-starter-blog-post (previous link), and expands upon it with a bunch of features and some more advanced functionality
+* [`@dschau/gatsby-blog-starter-kit`][source-code]
+ * A working repo demonstrating all of the aforementioned functionality of
+ Gatsby
+* [`@dschau/create-gatsby-blog-post`][create-gatsby-blog-post]
+ * A utility and CLI I created to scaffold out a blog post following the
+ predefined Gatsby structure with frontmatter, date, path, etc.
+* [Source code for my blog][blog-source-code]
+ * The source code for my blog, which takes the gatsby-starter-blog-post
+ (previous link), and expands upon it with a bunch of features and some more
+ advanced functionality
[react-dom-server]: https://facebook.github.io/react/docs/react-dom-server.html
[gatsby-release]: /blog/gatsby-v1/
-
[gatsby-plugins]: /docs/plugins/
-
[gatsby-plugin-catch-links]: /packages/gatsby-plugin-catch-links/
[gatsby-plugin-react-helmet]: /packages/gatsby-plugin-react-helmet/
[gatsby-plugin-preact]: /packages/gatsby-plugin-preact/
-
[gatsby-transformer-remark]: /packages/gatsby-transformer-remark/
[remark]: https://github.com/wooorm/remark
-
[gatsby-source-filesystem]: /packages/gatsby-source-filesystem/
-
[react-helmet]: https://github.com/nfl/react-helmet
-
[frontmatter]: https://jekyllrb.com/docs/frontmatter/
-
[learn-graphql]: https://www.howtographql.com
[node-spec]: /docs/node-apis/
[gatsby-bound-action-creators]: /docs/bound-action-creators/
-
[styled-components]: https://github.com/styled-components/styled-components
-
[yarn]: https://yarnpkg.com/en/
[source-code]: https://github.com/dschau/gatsby-blog-starter-kit
[blog-source-code]: https://github.com/dschau/blog
diff --git a/docs/blog/2017-09-13-why-is-gatsby-so-fast/index.md b/docs/blog/2017-09-13-why-is-gatsby-so-fast/index.md
index b46083cd9bc8c..c312c40791e8d 100644
--- a/docs/blog/2017-09-13-why-is-gatsby-so-fast/index.md
+++ b/docs/blog/2017-09-13-why-is-gatsby-so-fast/index.md
@@ -7,7 +7,9 @@ showImageInArticle: false
typora-copy-images-to: ./
---
-_I gave this talk last weekend at [ReactNext](http://react-next.com/) in Tel Aviv. I spoke on the basics of measuring and improving web performance and how Gatsby is designed so sites built with it are always very very fast._
+_I gave this talk last weekend at [ReactNext](http://react-next.com/) in Tel
+Aviv. I spoke on the basics of measuring and improving web performance and how
+Gatsby is designed so sites built with it are always very very fast._
_Slides to follow interspersed with notes._
@@ -19,17 +21,23 @@ _Slides to follow interspersed with notes._
![reactnext-gatsby-performance.008](reactnext-gatsby-performance.008.png)
-I open sourced the initial prototype of Gatsby in mid-2015. A year later, post failed startup, I went full-time on Gatsby as it seemed the most interesting and potentially fruitful thing I could do. After ten months of work, I, along with the 40 other contributors, released Gatsby v1. I'm currently working on a Gatsby-related startup.
+I open sourced the initial prototype of Gatsby in mid-2015. A year later, post
+failed startup, I went full-time on Gatsby as it seemed the most interesting and
+potentially fruitful thing I could do. After ten months of work, I, along with
+the 40 other contributors, released Gatsby v1. I'm currently working on a
+Gatsby-related startup.
![reactnext-gatsby-performance.007](reactnext-gatsby-performance.007.png)
## Why is site speed so important?
-DoubleClick ran a study on how site loading performance affected how people used websites.
+DoubleClick ran a study on how site loading performance affected how people used
+websites.
![reactnext-gatsby-performance.011](reactnext-gatsby-performance.011.png)
-In other words, PEOPLE LEAVE YOUR SITE IF IT IS SLOW. Which, I'll guess, is not what you want.
+In other words, PEOPLE LEAVE YOUR SITE IF IT IS SLOW. Which, I'll guess, is not
+what you want.
![reactnext-gatsby-performance.012](reactnext-gatsby-performance.012.png)
@@ -39,25 +47,33 @@ Slow loading sites tend to have many related performance problems.
## How to think about & measure performance?
-Ok, I've convinced you that site performance is important. You perhaps already have a site that you know is too slow. How to do you go about improving things?
+Ok, I've convinced you that site performance is important. You perhaps already
+have a site that you know is too slow. How to do you go about improving things?
-Our first task is to understand how to measure website performance. Only then can we make changes that we're confident are improving things.
+Our first task is to understand how to measure website performance. Only then
+can we make changes that we're confident are improving things.
-Let's discuss two key website performance metrics that summarize the most important parts of website performance. How quickly is your website visible (Speed Index) and how quickly is your site usable (Time to Interactive—TTI).
+Let's discuss two key website performance metrics that summarize the most
+important parts of website performance. How quickly is your website visible
+(Speed Index) and how quickly is your site usable (Time to Interactive—TTI).
![reactnext-gatsby-performance.015](reactnext-gatsby-performance.015.png)
![reactnext-gatsby-performance.016](reactnext-gatsby-performance.016-5314582.png)
-[webpagetest.org](http://webpagetest.org) is *so* good. I've run 100s if not 1000s of performance tests while working on sites and optimizing Gatsby.
+[webpagetest.org](http://webpagetest.org) is _so_ good. I've run 100s if not
+1000s of performance tests while working on sites and optimizing Gatsby.
![reactnext-gatsby-performance.021](reactnext-gatsby-performance.021.png)
## Performance tests on real websites
-Let's dive into some tests I ran on webpagetest.org and see the Speed Index score for some well-known sites.
+Let's dive into some tests I ran on webpagetest.org and see the Speed Index
+score for some well-known sites.
-Each test uses webpagetest's "Simple Testing" mode and the "Mobile - Regular 3G" test configuration. This loads a website from a real phone in Virginia USA (Motorola G gen 4) on a simulated 3G connection.
+Each test uses webpagetest's "Simple Testing" mode and the "Mobile - Regular 3G"
+test configuration. This loads a website from a real phone in Virginia USA
+(Motorola G gen 4) on a simulated 3G connection.
![reactnext-gatsby-performance.022](reactnext-gatsby-performance.022.png)
@@ -65,7 +81,9 @@ Each test uses webpagetest's "Simple Testing" mode and the "Mobile - Regular 3G"
![reactnext-gatsby-performance.024](reactnext-gatsby-performance.024.png)
-So CNN seems decent. Its Speed Index score is 8098 (these are milliseconds btw so 8.1 seconds) and it gets some pixels on screen by 6.5 seconds. Not bad. Let's look at the next site.
+So CNN seems decent. Its Speed Index score is 8098 (these are milliseconds btw
+so 8.1 seconds) and it gets some pixels on screen by 6.5 seconds. Not bad. Let's
+look at the next site.
![reactnext-gatsby-performance.025](reactnext-gatsby-performance.025.png)
@@ -73,7 +91,9 @@ So CNN seems decent. Its Speed Index score is 8098 (these are milliseconds btw s
![reactnext-gatsby-performance.027](reactnext-gatsby-performance.027.png)
-Hey nice! Its Speed Index score is 5568 so 2.5 seconds or so faster than CNN. It also gets its first pixels on screen at a zippy 3 seconds but its Speed Index score is hurt by it taking another *12 seconds* to finish loading.
+Hey nice! Its Speed Index score is 5568 so 2.5 seconds or so faster than CNN. It
+also gets its first pixels on screen at a zippy 3 seconds but its Speed Index
+score is hurt by it taking another _12 seconds_ to finish loading.
![reactnext-gatsby-performance.028](reactnext-gatsby-performance.028-5471130.png)
@@ -81,7 +101,9 @@ Hey nice! Its Speed Index score is 5568 so 2.5 seconds or so faster than CNN. It
![reactnext-gatsby-performance.030](reactnext-gatsby-performance.030.png)
-Washingtonpost.com gets its first significant paint at around 5 seconds but it takes another *10 seconds* to finish visually loading which hurts its Speed Index score some.
+Washingtonpost.com gets its first significant paint at around 5 seconds but it
+takes another _10 seconds_ to finish visually loading which hurts its Speed
+Index score some.
![reactnext-gatsby-performance.031](reactnext-gatsby-performance.031.png)
@@ -91,13 +113,19 @@ Washingtonpost.com gets its first significant paint at around 5 seconds but it t
Woah! **2365** Speed Index! gatsbyjs.org—stop making everyone look so bad! 😎
-And notice how steep the visual progress line is. Gatsby knows where it's going and gets there quick.
+And notice how steep the visual progress line is. Gatsby knows where it's going
+and gets there quick.
-gatsbyjs.org starts rendering 2x faster than cnn.com and washingtonpost.com and whereas downy.com starts rendering at the same time, its Speed Index is *2x* gatsbyjs.org due to the 12 seconds it takes to finish loading.
+gatsbyjs.org starts rendering 2x faster than cnn.com and washingtonpost.com and
+whereas downy.com starts rendering at the same time, its Speed Index is _2x_
+gatsbyjs.org due to the 12 seconds it takes to finish loading.
![reactnext-gatsby-performance.034](reactnext-gatsby-performance.034.png)
-I call slow TTIs the "silent killer" because it's obvious to most people when your Speed Index is slow. But slow TTI expresses itself in a 100 different UX frustrations which might not have an obvious source which is why this number is so important to track.
+I call slow TTIs the "silent killer" because it's obvious to most people when
+your Speed Index is slow. But slow TTI expresses itself in a 100 different UX
+frustrations which might not have an obvious source which is why this number is
+so important to track.
![reactnext-gatsby-performance.035](reactnext-gatsby-performance.035.png)
@@ -105,7 +133,9 @@ I call slow TTIs the "silent killer" because it's obvious to most people when yo
![reactnext-gatsby-performance.037](reactnext-gatsby-performance.037.png)
-Which is close to 1/2 of an eternity in web browsing time. And makes for a very frustrating user experience. Tapping on things that don't respond scores very high on the Annoying UX metric.
+Which is close to 1/2 of an eternity in web browsing time. And makes for a very
+frustrating user experience. Tapping on things that don't respond scores very
+high on the Annoying UX metric.
### Let's review our scores
@@ -129,7 +159,8 @@ Let's discuss some ways to improve performance.
![reactnext-gatsby-performance.039](reactnext-gatsby-performance.039.png)
-Clickable link—https://developers.google.com/web/fundamentals/performance/critical-rendering-path/
+Clickable
+link—https://developers.google.com/web/fundamentals/performance/critical-rendering-path/
![reactnext-gatsby-performance.040](reactnext-gatsby-performance.040.png)
@@ -139,7 +170,11 @@ If it doesn't need done immediately, defer it.
![reactnext-gatsby-performance.042](reactnext-gatsby-performance.042.png)
-We won't discuss code splitting in depth but the basic idea is *only load JavaScript* that is needed immediately on the initial landing page. Defer loading JavaScript for other pages. Defer loading optional JavaScript for the page (e.g. a widget down the page). And so on. The less JavaScript you load upfront, the faster your users will able to start using your site.
+We won't discuss code splitting in depth but the basic idea is _only load
+JavaScript_ that is needed immediately on the initial landing page. Defer
+loading JavaScript for other pages. Defer loading optional JavaScript for the
+page (e.g. a widget down the page). And so on. The less JavaScript you load
+upfront, the faster your users will able to start using your site.
![reactnext-gatsby-performance.043](reactnext-gatsby-performance.043.png)
@@ -147,7 +182,7 @@ There's plenty of in-depth resources you can Google for.
![reactnext-gatsby-performance.044](reactnext-gatsby-performance.044.png)
-*…perhaps you were wondering when I'd get to this*
+_…perhaps you were wondering when I'd get to this_
![reactnext-gatsby-performance.045](reactnext-gatsby-performance.045.png)
@@ -155,7 +190,8 @@ What is the magic here? How are Gatsby sites consistently so fast?
![reactnext-gatsby-performance.046](reactnext-gatsby-performance.046.png)
-Most frameworks leave frontend performance to users to figure out. With Gatsby it's fundamental.
+Most frameworks leave frontend performance to users to figure out. With Gatsby
+it's fundamental.
![reactnext-gatsby-performance.047](reactnext-gatsby-performance.047.png)
@@ -173,15 +209,19 @@ Most frameworks leave frontend performance to users to figure out. With Gatsby i
![reactnext-gatsby-performance.060](reactnext-gatsby-performance.060.png)
-I mean I *love* performance but even I really don't want to be worrying about this stuff when I'm pushing hard to finish up a project.
+I mean I _love_ performance but even I really don't want to be worrying about
+this stuff when I'm pushing hard to finish up a project.
![reactnext-gatsby-performance.061](reactnext-gatsby-performance.061.png)
-As browsers and tooling gets more sophisticated, "best practices" for building the most performant website changes.
+As browsers and tooling gets more sophisticated, "best practices" for building
+the most performant website changes.
![reactnext-gatsby-performance.062](reactnext-gatsby-performance.062.png)
-Even really large sites with dozens of engineers get things wrong all the time. For an entertaining & informative examination of this, checkout [Sam Saccone's blog](http://samsaccone.com).
+Even really large sites with dozens of engineers get things wrong all the time.
+For an entertaining & informative examination of this, checkout
+[Sam Saccone's blog](http://samsaccone.com).
![reactnext-gatsby-performance.063](reactnext-gatsby-performance.063.png)
@@ -193,11 +233,17 @@ Even really large sites with dozens of engineers get things wrong all the time.
![reactnext-gatsby-performance.067](reactnext-gatsby-performance.067.png)
-Gatsby is a [metacompiler](https://en.wikipedia.org/wiki/Metacompiler) if you will. It takes your site and from it compiles an optimized webpack/Babel configuration for building the site. In addition, it generates a client runtime to efficiently prefetch resources in the client so clicking around your site is lightning fast.
+Gatsby is a [metacompiler](https://en.wikipedia.org/wiki/Metacompiler) if you
+will. It takes your site and from it compiles an optimized webpack/Babel
+configuration for building the site. In addition, it generates a client runtime
+to efficiently prefetch resources in the client so clicking around your site is
+lightning fast.
![reactnext-gatsby-performance.068](reactnext-gatsby-performance.068.png)
-As I was prepping for my talk, Tom Dale of Ember, conveniently made similar points in [his great blog post](https://tomdale.net/2017/09/compilers-are-the-new-frameworks/).
+As I was prepping for my talk, Tom Dale of Ember, conveniently made similar
+points in
+[his great blog post](https://tomdale.net/2017/09/compilers-are-the-new-frameworks/).
![reactnext-gatsby-performance.069](reactnext-gatsby-performance.069.png)
@@ -211,8 +257,17 @@ As I was prepping for my talk, Tom Dale of Ember, conveniently made similar poin
## Performance is hard. Let's make Gatsby do the work.
-Building highly performant websites is a science in and of itself. Our goal with Gatsby is to give you an approachable, highly productive modern development environment that lets you concentrate on what matters to you—content, design, and interactions—and we take care of turning your amazing site into the fastest site possible.
+Building highly performant websites is a science in and of itself. Our goal with
+Gatsby is to give you an approachable, highly productive modern development
+environment that lets you concentrate on what matters to you—content, design,
+and interactions—and we take care of turning your amazing site into the fastest
+site possible.
-If you've been waiting to try out React, Gatsby is a great place to start! If you're struggling to make your React app fast, try switching to Gatsby! If you're tired of using technology X to build websites and have a huge secret crush on React, well, Gatsby is waiting with open arms 🤗
+If you've been waiting to try out React, Gatsby is a great place to start! If
+you're struggling to make your React app fast, try switching to Gatsby! If
+you're tired of using technology X to build websites and have a huge secret
+crush on React, well, Gatsby is waiting with open arms 🤗
-And lastly, *if you're a performance-obsessed engineer like me, come help build Gatsby* and improve the performance of thousands (numbers growing quickly) of Gatsby sites on the internet.
+And lastly, _if you're a performance-obsessed engineer like me, come help build
+Gatsby_ and improve the performance of thousands (numbers growing quickly) of
+Gatsby sites on the internet.
diff --git a/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md b/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md
index 0f2179d249dd2..7320c8c980dfd 100644
--- a/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md
+++ b/docs/blog/2017-09-18-gatsby-modern-static-generation/index.md
@@ -6,38 +6,71 @@ author: "Kostas Bariotis"
excerpt: "In this post, I will talk about static site generators -- how they have evolved and why I switched from a Ghost powered site to Gatsby.js, a modern static site generator."
---
-In this post, I will talk about static site generators -- how they have evolved and why I switched from a [Ghost](https://ghost.org) powered site to [Gatsby.js](/), a modern static site generator.
+In this post, I will talk about static site generators -- how they have evolved
+and why I switched from a [Ghost](https://ghost.org) powered site to
+[Gatsby.js](/), a modern static site generator.
## Static site generators as we know them
-Jekyll, my tool of preference for quite a few years, helped me build [robust](http://devastation.tv) [professional](http://devitconf.org) [web presences](http://skgtech.io) that content managers can update with the click of a button. It helped me quickly move a project of mine from idea to production by creating a landing page very fast.
+
+Jekyll, my tool of preference for quite a few years, helped me build
+[robust](http://devastation.tv) [professional](http://devitconf.org)
+[web presences](http://skgtech.io) that content managers can update with the
+click of a button. It helped me quickly move a project of mine from idea to
+production by creating a landing page very fast.
Static site generators like Jekyll all work pretty similarly:
-* Describe your content in some common templating language ([Pug](pugjs.org), [Handlebars](http://handlebarsjs.com), etc)
-* While in development, start a local web server and add file "watchers" that will listen for content changes and re-render the site
-* Finally, render the whole site in static HTML and deploy. The generator will combine your files and produce a well formed HTML content.
+* Describe your content in some common templating language ([Pug](pugjs.org),
+ [Handlebars](http://handlebarsjs.com), etc)
+* While in development, start a local web server and add file "watchers" that
+ will listen for content changes and re-render the site
+* Finally, render the whole site in static HTML and deploy. The generator will
+ combine your files and produce a well formed HTML content.
Let’s say you navigate to the good old site example.com:
* The browser requests the page at example.com
* The server responds with the HTML content
* The browser renders the page and loads the asset related to the script tag
-* JS will instruct the browser to manipulate the DOM, for example, to show a “welcome to this page” popup dialog.
+* JS will instruct the browser to manipulate the DOM, for example, to show a
+ “welcome to this page” popup dialog.
-A caveat here is that you have to keep the client side logic separated from the backend. The client side JS file that shows the modal dialog has nothing to do with the PUG file you wrote and eventually became HTML. The client side logic only manipulates directly the DOM.
+A caveat here is that you have to keep the client side logic separated from the
+backend. The client side JS file that shows the modal dialog has nothing to do
+with the PUG file you wrote and eventually became HTML. The client side logic
+only manipulates directly the DOM.
-This architecture is fairly similar to a Wordpress site. A Wordpress engine also generates the HTML and serve it to the browser, after which the client side JS you wrote kicks in and starts manipulating the DOM. Wordpress’s responses can be cached, of course, and served to the client; that setup effectively makes it another static site generator with a GUI text editor.
+This architecture is fairly similar to a Wordpress site. A Wordpress engine also
+generates the HTML and serve it to the browser, after which the client side JS
+you wrote kicks in and starts manipulating the DOM. Wordpress’s responses can be
+cached, of course, and served to the client; that setup effectively makes it
+another static site generator with a GUI text editor.
-So to recap, the nice part of the static site setup is that your website is just static assets that are sitting somewhere ready to be served to user requests. No need to maintain a runtime, a database, application code, or complex optimized web servers.
+So to recap, the nice part of the static site setup is that your website is just
+static assets that are sitting somewhere ready to be served to user requests. No
+need to maintain a runtime, a database, application code, or complex optimized
+web servers.
-But the downside is you have to keep separate template files that will eventually rendered as HTML on the browser, and Javascript file that will eventually manipulate that HTML again on the browser (and CSS assets too).
+But the downside is you have to keep separate template files that will
+eventually rendered as HTML on the browser, and Javascript file that will
+eventually manipulate that HTML again on the browser (and CSS assets too).
## Enter the new world order
-I [started experimenting](https://kostasbariotis.com/hands-on-react-js/) with React two years ago. It came with so many features out of the box that no one ever has seen except the guys working internally on Facebook’s codebase. But the thing that stood out immediately was the way which React was handling the DOM, aka the Virtual DOM.
-To change a page’s display, you have to change the DOM -- but changing the DOM is computationally expensive, so -- slow. React is smart, and analyzes the changes you want to make so it applies only required changes, thus making the rendering much faster.
+I [started experimenting](https://kostasbariotis.com/hands-on-react-js/) with
+React two years ago. It came with so many features out of the box that no one
+ever has seen except the guys working internally on Facebook’s codebase. But the
+thing that stood out immediately was the way which React was handling the DOM,
+aka the Virtual DOM.
+
+To change a page’s display, you have to change the DOM -- but changing the DOM
+is computationally expensive, so -- slow. React is smart, and analyzes the
+changes you want to make so it applies only required changes, thus making the
+rendering much faster.
-If you use React with [server-side rendering](https://facebook.github.io/react/docs/react-dom-server.html), your flow looks something like this:
+If you use React with
+[server-side rendering](https://facebook.github.io/react/docs/react-dom-server.html),
+your flow looks something like this:
* A browser requests a page
* The server responds with static HTML
@@ -49,54 +82,105 @@ If you use React with [server-side rendering](https://facebook.github.io/react/d
On your end, the development flow looks:
* Describe your content in React.js Components
-* During development, write code like a boss (hot reloading, modularized code, webpack plugins, etc...)
-* Use React.js Server Side Rendering API to convert this code to static HTML content, and Javascript code, on your server
+* During development, write code like a boss (hot reloading, modularized code,
+ webpack plugins, etc...)
+* Use React.js Server Side Rendering API to convert this code to static HTML
+ content, and Javascript code, on your server
It’s really that easy? Well, sort of.
There is the need for a strong abstraction that will…
+
* track your links across your components
* parse content written in another format, like blog posts written in Markdown
-* generate code that will not bloat the client and will efficiently serve the content to the user.
+* generate code that will not bloat the client and will efficiently serve the
+ content to the user.
-Thankfully, there are a few projects that took the initiative on this: [Gatsby.js](/), [Phenomic](https://phenomic.io), and [nextein](https://nextein.now.sh).
+Thankfully, there are a few projects that took the initiative on this:
+[Gatsby.js](/), [Phenomic](https://phenomic.io), and
+[nextein](https://nextein.now.sh).
-At the time that I started following them, early 2017, all of them were in a very early stage and none of them could generate my site's content the way I wanted.
+At the time that I started following them, early 2017, all of them were in a
+very early stage and none of them could generate my site's content the way I
+wanted.
-I wanted to make the generated site, exactly like the old one, in terms of both user experience and keeping my old routes and paths so I don’t have weird 404s.
+I wanted to make the generated site, exactly like the old one, in terms of both
+user experience and keeping my old routes and paths so I don’t have weird 404s.
-Gatsby came with client side routing out of the box and an extensive API that you can use to generate your content exactly like you need. And once Gatsby.js hit major version 1, I started using it and the result...you can [look at it](https://kostasbariotis.com/)!
+Gatsby came with client side routing out of the box and an extensive API that
+you can use to generate your content exactly like you need. And once Gatsby.js
+hit major version 1, I started using it and the result...you can
+[look at it](https://kostasbariotis.com/)!
## What exactly am I looking at?
-First, if you navigate around my blog (or around this site!), you will notice that the browser doesn't fully re-render the site. Gatsby will generate a JSON file for each route, so the browser can request only that file and React.js will render only the appropriate components.
-
-(Previously to do this required a lot of customization -- I was using a technique called [pjax](https://github.com/kbariotis/kostasbariotis.com__ghost-theme/blob/master/src/js/app.js#L11) to create the same effect. While it looked the same, it was more hack-ish; Gatsby provides this out of the box)
-Second, you can take a look at the [source code](https://github.com/kbariotis/kostasbariotis.com).
-Let me give you a sense of how this site is being generated. You can find all my blog posts and the main pages(`/`, `/about`, `/drafts`) of this site at [`/src/pages`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/pages). Common components can be found at [`/src/components`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/components). At [`/gatsby-node.js`](https://github.com/kbariotis/kostasbariotis.com/tree/master/gatsby-node.js) you can find the route it takes in order to render the site. First, it loads all posts using the GraphQL api which queries all `.md` files. Then it creates a page for each one, using the [`/src/templates/blog-post.js`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/templates/blog-post.js) template and before that it creates a page, with pagination, for all posts and tags again using the appropriate template file.
-
-During development, Gatsby will generate all of these in memory and fire up a development server that I can use to preview my site.
-
-You can try it yourself by cloning the [source code](https://github.com/kbariotis/kostasbariotis.com) and after installing dependencies, run:
+First, if you navigate around my blog (or around this site!), you will notice
+that the browser doesn't fully re-render the site. Gatsby will generate a JSON
+file for each route, so the browser can request only that file and React.js will
+render only the appropriate components.
+
+(Previously to do this required a lot of customization -- I was using a
+technique called
+[pjax](https://github.com/kbariotis/kostasbariotis.com__ghost-theme/blob/master/src/js/app.js#L11)
+to create the same effect. While it looked the same, it was more hack-ish;
+Gatsby provides this out of the box)
+
+Second, you can take a look at the
+[source code](https://github.com/kbariotis/kostasbariotis.com). Let me give you
+a sense of how this site is being generated. You can find all my blog posts and
+the main pages(`/`, `/about`, `/drafts`) of this site at
+[`/src/pages`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/pages).
+Common components can be found at
+[`/src/components`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/components).
+At
+[`/gatsby-node.js`](https://github.com/kbariotis/kostasbariotis.com/tree/master/gatsby-node.js)
+you can find the route it takes in order to render the site. First, it loads all
+posts using the GraphQL api which queries all `.md` files. Then it creates a
+page for each one, using the
+[`/src/templates/blog-post.js`](https://github.com/kbariotis/kostasbariotis.com/tree/master/src/templates/blog-post.js)
+template and before that it creates a page, with pagination, for all posts and
+tags again using the appropriate template file.
+
+During development, Gatsby will generate all of these in memory and fire up a
+development server that I can use to preview my site.
+
+You can try it yourself by cloning the
+[source code](https://github.com/kbariotis/kostasbariotis.com) and after
+installing dependencies, run:
* `npm run develop` to fire up the development server
* `npm run build` to build the site (check the `/public` folder after it’s done)
## An alternative to HTML caching
-Now let’s bring these threads together. Let’s say you have a Wordpress site. You’re caching the content, which is nice for performance, but you’re building on it now and want to move to a more modern web development experience.
-One path is the one I took -- for the last three years, I was using a similar system called [Ghost](https://ghost.org). While it served me well, I really got tired of updating it, ssh-ing to the server, doing migrations and doing other ops required by such a stack. (There are paid hosting options, of course, but that comes with a different set of problems). So I switched to Gatsby.
+Now let’s bring these threads together. Let’s say you have a Wordpress site.
+You’re caching the content, which is nice for performance, but you’re building
+on it now and want to move to a more modern web development experience.
-Another option, if you want to keep Wordpress' Admin UI is to maintain your content, is to separate the backend from the frontend.
+One path is the one I took -- for the last three years, I was using a similar
+system called [Ghost](https://ghost.org). While it served me well, I really got
+tired of updating it, ssh-ing to the server, doing migrations and doing other
+ops required by such a stack. (There are paid hosting options, of course, but
+that comes with a different set of problems). So I switched to Gatsby.
-Imagine that instead of having [memcached](https://memcached.org/) caching your HTML in front of your WordPress site, you trigger a hook each time your database changes that will re-generate the frontend using Gatsby’s [Wordpress plugin](/packages/gatsby-source-wordpress/). Yes, Gatsby supports multiple backend sources to load your content. Instead of storing them inside your version control like me, you can just as well load them from your Wordpress's MySQL database.
+Another option, if you want to keep Wordpress' Admin UI is to maintain your
+content, is to separate the backend from the frontend.
+
+Imagine that instead of having [memcached](https://memcached.org/) caching your
+HTML in front of your WordPress site, you trigger a hook each time your database
+changes that will re-generate the frontend using Gatsby’s
+[Wordpress plugin](/packages/gatsby-source-wordpress/). Yes, Gatsby supports
+multiple backend sources to load your content. Instead of storing them inside
+your version control like me, you can just as well load them from your
+Wordpress's MySQL database.
To conclude, Gatsby will allow us to:
* serve static content without maintaining complex stacks
* keep a clear separation between content and the presentation layer
-* have cool features like client side routing and hot reload on development, out of the box
-* reuse the same code that is being used to generate the backend content at our visitors' browsers
+* have cool features like client side routing and hot reload on development, out
+ of the box
+* reuse the same code that is being used to generate the backend content at our
+ visitors' browsers
I hope you will experiment with Gatsby, and let me know what you think!
-
diff --git a/docs/blog/2017-09-21-community-roundup-1/index.md b/docs/blog/2017-09-21-community-roundup-1/index.md
index f40a67b47cba8..620cdcaf081f4 100644
--- a/docs/blog/2017-09-21-community-roundup-1/index.md
+++ b/docs/blog/2017-09-21-community-roundup-1/index.md
@@ -7,7 +7,8 @@ showImageInArticle: true
typora-copy-images-to: ./
---
-It's been a wild 77 days since Gatsby 1.0.0 was released into the world on July 6th, 2017.
+It's been a wild 77 days since Gatsby 1.0.0 was released into the world on July
+6th, 2017.
By the numbers we've seen:
@@ -19,23 +20,58 @@ By the numbers we've seen:
## New Gatsby sites launched recently
-* Sourcegraph, a startup that helps developers discover and understand code, [relaunched their site on Gatsby](https://about.sourcegraph.com/)
-* The customer data platform startup mParticle [launched their docs site on Gatsby](https://docs.mparticle.com/)
-* The hip new Ocaml-based programming language ReasonML [built their new website on Gatsby](https://reasonml.github.io/)
-* Freelancer web developer [Oliver Benns'](https://twitter.com/oliverbenns/) [portfolio site](https://oliverbenns.com/)
-* [Daniel Stefanovic](https://twitter.com/danistefanovic) launched his online book http://digitalpsychology.io/
+* Sourcegraph, a startup that helps developers discover and understand code,
+ [relaunched their site on Gatsby](https://about.sourcegraph.com/)
+* The customer data platform startup mParticle
+ [launched their docs site on Gatsby](https://docs.mparticle.com/)
+* The hip new Ocaml-based programming language ReasonML
+ [built their new website on Gatsby](https://reasonml.github.io/)
+* Freelancer web developer [Oliver Benns'](https://twitter.com/oliverbenns/)
+ [portfolio site](https://oliverbenns.com/)
+* [Daniel Stefanovic](https://twitter.com/danistefanovic) launched his online
+ book http://digitalpsychology.io/
-## New tutorials!
+## New tutorials!
-* The official tutorial has been growing slowly. The first four parts are finished covering the basics of starting new projects, exploring styling options, how to use Gatsby plugins, and the basics of Gatsby's GraphQL data layer. [Check them out!](/tutorial/)
-* Level Up Tutorials is working on a new Gatsby video tutorial series! It's fantastic! [Check out the first 7 tutorials on YouTube!](https://www.youtube.com/watch?v=b2H7fWhQcdE&list=PLLnpHn493BHHfoINKLELxDch3uJlSapxg). Scott Tolinski also recorded two other videos on Gatsby, his ["first look" at Gatsby](https://www.youtube.com/watch?v=CSemYFzHAtU) shortly after its 1.0 release as well as a [recording of him moving his personal site to Gatsby](https://www.youtube.com/watch?v=xqaThBnesfY).
-* [Giraffe Academy launched a new Gatsby tutorial series](https://www.youtube.com/playlist?list=PLLAZ4kZ9dFpMXuwazIt4mWtTuqOHdjRlk)! 13 tutorials so far covering everything from setting up Gatsby on your computer to building with React components to working with different types of data.
+* The official tutorial has been growing slowly. The first four parts are
+ finished covering the basics of starting new projects, exploring styling
+ options, how to use Gatsby plugins, and the basics of Gatsby's GraphQL data
+ layer. [Check them out!](/tutorial/)
+* Level Up Tutorials is working on a new Gatsby video tutorial series! It's
+ fantastic!
+ [Check out the first 7 tutorials on YouTube!](https://www.youtube.com/watch?v=b2H7fWhQcdE&list=PLLnpHn493BHHfoINKLELxDch3uJlSapxg).
+ Scott Tolinski also recorded two other videos on Gatsby, his
+ ["first look" at Gatsby](https://www.youtube.com/watch?v=CSemYFzHAtU) shortly
+ after its 1.0 release as well as a
+ [recording of him moving his personal site to Gatsby](https://www.youtube.com/watch?v=xqaThBnesfY).
+* [Giraffe Academy launched a new Gatsby tutorial series](https://www.youtube.com/playlist?list=PLLAZ4kZ9dFpMXuwazIt4mWtTuqOHdjRlk)!
+ 13 tutorials so far covering everything from setting up Gatsby on your
+ computer to building with React components to working with different types of
+ data.
## Notable plugins launched
-* The WordPress plugin recently got a big revamp and hit 2.0.0! Checkout the [new example site](https://using-wordpress.gatsbyjs.org/) and the [README](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-wordpress)
-* Several new CSS plugins have been added, [Less](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-less), [Emotion](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-emotion), [Styled JSX](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-styled-jsx), [JSS](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-jss), and [Stylus](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-stylus)!
-* [Tumblbug](https://www.tumblbug.com/), a startup in South Korea, built a [source plugin for Workable](https://github.com/tumblbug/gatsby-source-workable) so they could easily load job listings into their website.
-* [Ryan Florence](https://twitter.com/ryanflorence) built a [source plugin for Firebase](https://github.com/ReactTraining/gatsby-source-firebase) so he could easily query data stored there while rebuilding his company website!
-* [gatsby-remark-katex](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-katex) lets you write math equations in your markdown and [see them beautifully rendered](https://using-remark.gatsbyjs.org/katex/).
-* [gatsby-plugin-purify-css](https://github.com/rongierlach/gatsby-plugin-purify-css) adds drop-in support for removing unused CSS during Gatsby builds! It uses [PurifyCSS](https://github.com/purifycss/purifycss) and can lead to huge reductions in CSS weight.
+* The WordPress plugin recently got a big revamp and hit 2.0.0! Checkout the
+ [new example site](https://using-wordpress.gatsbyjs.org/) and the
+ [README](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-wordpress)
+* Several new CSS plugins have been added,
+ [Less](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-less),
+ [Emotion](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-emotion),
+ [Styled JSX](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-styled-jsx),
+ [JSS](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-jss),
+ and
+ [Stylus](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-stylus)!
+* [Tumblbug](https://www.tumblbug.com/), a startup in South Korea, built a
+ [source plugin for Workable](https://github.com/tumblbug/gatsby-source-workable)
+ so they could easily load job listings into their website.
+* [Ryan Florence](https://twitter.com/ryanflorence) built a
+ [source plugin for Firebase](https://github.com/ReactTraining/gatsby-source-firebase)
+ so he could easily query data stored there while rebuilding his company
+ website!
+* [gatsby-remark-katex](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-katex)
+ lets you write math equations in your markdown and
+ [see them beautifully rendered](https://using-remark.gatsbyjs.org/katex/).
+* [gatsby-plugin-purify-css](https://github.com/rongierlach/gatsby-plugin-purify-css)
+ adds drop-in support for removing unused CSS during Gatsby builds! It uses
+ [PurifyCSS](https://github.com/purifycss/purifycss) and can lead to huge
+ reductions in CSS weight.
diff --git a/docs/blog/2017-09-26-embracing-graphql/index.md b/docs/blog/2017-09-26-embracing-graphql/index.md
index e856ea14cedcc..b3a3d9c16fba1 100644
--- a/docs/blog/2017-09-26-embracing-graphql/index.md
+++ b/docs/blog/2017-09-26-embracing-graphql/index.md
@@ -6,7 +6,8 @@ author: "Tim Arney"
excerpt: "Moving to Gatsby 1.x and embracing the new GraphQL setup can be daunting but the effort is going to payoff"
---
-Before I built [React FAQ](https://reactfaq.site/), I went looking for a static site generator.
+Before I built [React FAQ](https://reactfaq.site/), I went looking for a static
+site generator.
I had a few criteria in mind.
@@ -15,17 +16,23 @@ I had a few criteria in mind.
* React-based
* Easy to update
-Gatsby at the time was still pre-1.0 but its workflow met my needs. I loved that I could drop my existing Markdown files into a `pages` directory and Gatsby would do the rest.
+Gatsby at the time was still pre-1.0 but its workflow met my needs. I loved that
+I could drop my existing Markdown files into a `pages` directory and Gatsby
+would do the rest.
Webpack loader —> React.js wrapper component —> static HTML page. Done.
-Well...done until I read this [GitHub Issue](https://github.com/gatsbyjs/gatsby/issues/420) … "New GraphQL data layer".
+Well...done until I read this
+[GitHub Issue](https://github.com/gatsbyjs/gatsby/issues/420) … "New GraphQL
+data layer".
-![issue-420](issue-420.png)
+![issue-420](issue-420.png)
-Things in Gatsby were about to change. I read on to see how easy it’d be to upgrade.
+Things in Gatsby were about to change. I read on to see how easy it’d be to
+upgrade.
-Having never used GraphQL, the new “routeQuery” in components looked very foreign.
+Having never used GraphQL, the new “routeQuery” in components looked very
+foreign.
```javascript
export const routeQuery = `
@@ -43,15 +50,19 @@ export const routeQuery = `
}
```
-What happened to my “drop files into a folder and call it a day” setup? What _is_ all this weird syntax [@kylemathews](https://twitter.com/kylemathews)?
+What happened to my “drop files into a folder and call it a day” setup? What
+_is_ all this weird syntax [@kylemathews](https://twitter.com/kylemathews)?
-Reading the issue, Kyle's reasoning made sense but this didn't seem to be simple at all. 0.x seemed more “automatic” to me. Drop in your files and go.
+Reading the issue, Kyle's reasoning made sense but this didn't seem to be simple
+at all. 0.x seemed more “automatic” to me. Drop in your files and go.
## 1.0 Released
-When 1.0 landed, I waited for a while before trying to update my website. The reviews were solid but I was still stuck on my pre-1.0 mindset.
+When 1.0 landed, I waited for a while before trying to update my website. The
+reviews were solid but I was still stuck on my pre-1.0 mindset.
-Then three weeks ago I saw this tweet from [@ryanflorence](https://twitter.com/ryanflorence):
+Then three weeks ago I saw this tweet from
+[@ryanflorence](https://twitter.com/ryanflorence):
@@ -59,27 +70,51 @@ Well, that sounded like a pretty good endorsement.
## Taking the leap
-With the [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog) in hand as a solid example, I started converting my website over to v1.0.
+With the [gatsby-starter-blog](https://github.com/gatsbyjs/gatsby-starter-blog)
+in hand as a solid example, I started converting my website over to v1.0.
-There were a few bumps into the road but thanks to the starter example, I pieced things together quickly. Quickly as in “I have no idea how this GraphQL stuff works, but I have it working, so cool”. Easy to update — check.
+There were a few bumps into the road but thanks to the starter example, I pieced
+things together quickly. Quickly as in “I have no idea how this GraphQL stuff
+works, but I have it working, so cool”. Easy to update — check.
## Digging Deeper
-I'm not the type of person to settle on “It's working so don't touch anything”. So I started digging into how Gatsby 1.x works—particular the [data layer](https://www.gatsbyjs.org/tutorial/part-four/#data-in-gatsby).
+I'm not the type of person to settle on “It's working so don't touch anything”.
+So I started digging into how Gatsby 1.x works—particular the
+[data layer](https://www.gatsbyjs.org/tutorial/part-four/#data-in-gatsby).
-Things really clicked when I read this part about the GraphiQL IDE and watched how to drill down on the data.
+Things really clicked when I read this part about the GraphiQL IDE and watched
+how to drill down on the data.
-![GraphiQL](graphiql.gif)
+![GraphiQL](graphiql.gif)
-Prior to reading / seeing that part in the documentation, looking at the code I could understand roughly what was going on but it didn’t feel familiar. Like anything new, there’s that “I don’t know what I’m doing” stage. I know what I want to do, but I don’t understand the syntax enough to make it happen. Seeing the docs and how you can explore the schema in GraphiQL (autocomplete is 👌) to see what data is available really helped in my “play around and break stuff” phase.
+Prior to reading / seeing that part in the documentation, looking at the code I
+could understand roughly what was going on but it didn’t feel familiar. Like
+anything new, there’s that “I don’t know what I’m doing” stage. I know what I
+want to do, but I don’t understand the syntax enough to make it happen. Seeing
+the docs and how you can explore the schema in GraphiQL (autocomplete is 👌) to
+see what data is available really helped in my “play around and break stuff”
+phase.
**From the docs:**
-> You first sketch out the data query by playing in GraphiQL, then copy this to a React page component to start building the UI.
-“Sketch & Copy” using the GraphiQL was a revelation. I was thinking it’s going to be tricky to manually write the queries until I become more familiar with the syntax. Using GraphiQL helped me make a quick leap forward with the learning curve. “Aha this is amazing”. I have lots to learn still but the comfort level is going up.
+> You first sketch out the data query by playing in GraphiQL, then copy this to
+> a React page component to start building the UI.
+
+“Sketch & Copy” using the GraphiQL was a revelation. I was thinking it’s going
+to be tricky to manually write the queries until I become more familiar with the
+syntax. Using GraphiQL helped me make a quick leap forward with the learning
+curve. “Aha this is amazing”. I have lots to learn still but the comfort level
+is going up.
## That's a wrap
-With my 1.x update complete, I'm feeling that not only was GatsbyJS a solid pick, but it's something that is going to evolve the way I build websites. It's a nice starter push into GraphQL and many other advanced features the websites of the future will need to be performant.
+With my 1.x update complete, I'm feeling that not only was GatsbyJS a solid
+pick, but it's something that is going to evolve the way I build websites. It's
+a nice starter push into GraphQL and many other advanced features the websites
+of the future will need to be performant.
-Sometimes we don’t do things because they are unfamiliar to us. Sometimes we need a little push. Thanks for the push GatsbyJS. The learning curve may seem daunting but the payoff is huge. GatsbyJS has become a powerful tool in my arsenal and I’m happy to have extended my development skills.
+Sometimes we don’t do things because they are unfamiliar to us. Sometimes we
+need a little push. Thanks for the push GatsbyJS. The learning curve may seem
+daunting but the payoff is huge. GatsbyJS has become a powerful tool in my
+arsenal and I’m happy to have extended my development skills.
diff --git a/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md b/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md
index 4e1d232e29bfb..b2963f4aec326 100644
--- a/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md
+++ b/docs/blog/2017-10-01-migrating-my-blog-from-hexo-to-gatsby/index.md
@@ -6,13 +6,19 @@ author: "Ian Sinnott"
excerpt: "How I migrated my blog to Gatsby and how you can do the same."
---
-_This article was originally posted on [my blog (original link)](https://blog.iansinnott.com/migrating-a-blog-to-gatsby-part-2-of-gatsby-migration/). I'm reposting here in the hopes that it helps more people get started with Gatsby!_
+_This article was originally posted on
+[my blog (original link)](https://blog.iansinnott.com/migrating-a-blog-to-gatsby-part-2-of-gatsby-migration/).
+I'm reposting here in the hopes that it helps more people get started with
+Gatsby!_
# Migrating a blog to Gatsby
---
-**Abstract:** Gatsby is a great tool for building a blog. In part 1 I did the more simple task of migrating an existing React site to Gatsby. This time I migrated my blog, which was a lot more involved and required a lot more Gatsby-specific knowledge.
+**Abstract:** Gatsby is a great tool for building a blog. In part 1 I did the
+more simple task of migrating an existing React site to Gatsby. This time I
+migrated my blog, which was a lot more involved and required a lot more
+Gatsby-specific knowledge.
Here's the gist of what I'm going to cover:
@@ -28,15 +34,28 @@ Let's jump in.
## Preparing your existing blog for migration
-**NOTE:** If you _don't_ already have a blog or want to create one from scratch there's a [tutorial for exactly that right here](https://www.gatsbyjs.org/blog/2017-07-19-creating-a-blog-with-gatsby/).
+**NOTE:** If you _don't_ already have a blog or want to create one from scratch
+there's a
+[tutorial for exactly that right here](https://www.gatsbyjs.org/blog/2017-07-19-creating-a-blog-with-gatsby/).
-Let's move some files around. Gatsby gives you a good amount of flexibility when it comes to file structure, but for consistency with the docs I'm going to use the suggested file structure for migrating my blog. How you handle this step will depend on what you're migrating from. I am migrating form Hexo, which is very similar to Jekyll in how it structures files.
+Let's move some files around. Gatsby gives you a good amount of flexibility when
+it comes to file structure, but for consistency with the docs I'm going to use
+the suggested file structure for migrating my blog. How you handle this step
+will depend on what you're migrating from. I am migrating form Hexo, which is
+very similar to Jekyll in how it structures files.
### Clean up your source repo
-For the first step, clear everything other than your actual post content out of the repo. For me, this meant everything that wasn't under the `source/` directory (that's a Hexo convention). One way to do this is to take everything not relevant to the upcoming Gatsby blog and move it into its own directory that doesn't interfere with anything. I chose to create `hexo.bak/` where all my old blog files would live (except for the content).
+For the first step, clear everything other than your actual post content out of
+the repo. For me, this meant everything that wasn't under the `source/`
+directory (that's a Hexo convention). One way to do this is to take everything
+not relevant to the upcoming Gatsby blog and move it into its own directory that
+doesn't interfere with anything. I chose to create `hexo.bak/` where all my old
+blog files would live (except for the content).
-You could also simply delete everything other than your raw content. It's up to you. But once your done with this cleanup you should have made a decision on where to hold your content, and moved everything else away or removed it.
+You could also simply delete everything other than your raw content. It's up to
+you. But once your done with this cleanup you should have made a decision on
+where to hold your content, and moved everything else away or removed it.
Here's what that looks like for me:
@@ -51,11 +70,13 @@ Here's what that looks like for me:
└── [ All my old hexo related files ... ]
```
-For the rest of this post I'll ignore the `hexo.bak/` directory because it's not relevant to Gatsby.
+For the rest of this post I'll ignore the `hexo.bak/` directory because it's not
+relevant to Gatsby.
## Set up Gatsby
-You need to copy all the standard Gatsby boilerplate into your directory. There are many ways you could do this but I'll go over what I did.
+You need to copy all the standard Gatsby boilerplate into your directory. There
+are many ways you could do this but I'll go over what I did.
To get all the Gatsby files you can use the Gatsby CLI.
@@ -66,7 +87,8 @@ cp -R temp-gatsby-files/* ./ # Copy all the files into your root directory
rm -rf temp-gatsby-files # Remove the temp directory
```
-However you get Gatsby initialized in your repository root, afterwards you should have a file structure that looks something like this:
+However you get Gatsby initialized in your repository root, afterwards you
+should have a file structure that looks something like this:
```
.
@@ -92,7 +114,8 @@ Now run the Gatsby dev server to make sure everything works:
npm run develop
```
-**NOTE:** If you open up `package.json` you can see what the `develop` script is doing.
+**NOTE:** If you open up `package.json` you can see what the `develop` script is
+doing.
Boom 💥! The default site is up.
@@ -100,7 +123,8 @@ Boom 💥! The default site is up.
## Rendering a list of posts
-Let's customize that landing page to render a list of posts. You will also probably want to customize the header and overall layout.
+Let's customize that landing page to render a list of posts. You will also
+probably want to customize the header and overall layout.
### Customizing the layout
@@ -110,9 +134,13 @@ This is pretty simple. Just modify the primary layout file that was generated:
src/layouts/index.js
```
-You can also customize the styles in `src/layouts/index.css`. Stylus, Sass, Less, etc are also supported if you add the appropriate plugin. [Here's the list](https://github.com/gatsbyjs/gatsby/tree/master/packages) (there's a page on the website too, but the source is more up to date).
+You can also customize the styles in `src/layouts/index.css`. Stylus, Sass,
+Less, etc are also supported if you add the appropriate plugin.
+[Here's the list](https://github.com/gatsbyjs/gatsby/tree/master/packages)
+(there's a page on the website too, but the source is more up to date).
-**Sidenote:** You can also create your own plugin to do whatever you want, which I talked about in part 1.
+**Sidenote:** You can also create your own plugin to do whatever you want, which
+I talked about in part 1.
### Customizing the landing page
@@ -122,29 +150,42 @@ Also straightforward, just edit:
src/pages/index.js
```
-This file is where we'll actually render out the list of posts. So where the hell does that data come from??
+This file is where we'll actually render out the list of posts. So where the
+hell does that data come from??
### Querying data with GraphQL
-Now we're getting in to the meat of Gatsby and one of the areas where it really shines: Data sources. You can pull in data from anywhere to be rendered in your blog, but for our use case the only data source will be the file system (aka the markdown files stored on your hard drive).
+Now we're getting in to the meat of Gatsby and one of the areas where it really
+shines: Data sources. You can pull in data from anywhere to be rendered in your
+blog, but for our use case the only data source will be the file system (aka the
+markdown files stored on your hard drive).
-But first, let's check out [GraphiQL][]. It's an excellent playground for testing out GraphQL queries in any GraphQL project. Gatsby ships with it enabled by default, thank goodness. GraphQL can actually be oddly opaque without this excellent tool.
+But first, let's check out [GraphiQL][]. It's an excellent playground for
+testing out GraphQL queries in any GraphQL project. Gatsby ships with it enabled
+by default, thank goodness. GraphQL can actually be oddly opaque without this
+excellent tool.
-Visit
in the browser and you'll be greeted with this lovely dev tool:
+Visit in the browser and you'll be greeted
+with this lovely dev tool:
![Gatsby Graphiql](https://dropsinn.s3.amazonaws.com/Screen%20Shot%202017-08-26%20at%201.31.08%20PM.png)
-I recommend getting to know this tool if you're not already familiar. You will be coming back to this often to find the right query to pull data for your pages.
+I recommend getting to know this tool if you're not already familiar. You will
+be coming back to this often to find the right query to pull data for your
+pages.
### Querying the file system
-If you play around with GraphiQL you'll notice there's not that much there. Let's fix that. We need to teach Gatsby how to query the file system. Luckily this is so common it's been done for you. Install the file system source plugin:
+If you play around with GraphiQL you'll notice there's not that much there.
+Let's fix that. We need to teach Gatsby how to query the file system. Luckily
+this is so common it's been done for you. Install the file system source plugin:
```
yarn add gatsby-source-filesystem
```
-Now modify `gatsby-config.js` to both use the plugin and tell it what directory to source files from. Add this to the `plugins` array:
+Now modify `gatsby-config.js` to both use the plugin and tell it what directory
+to source files from. Add this to the `plugins` array:
```js
{
@@ -156,9 +197,11 @@ Now modify `gatsby-config.js` to both use the plugin and tell it what directory
}
```
-As you can see on my system I keep all my markdown files under `content/_posts/` which is reflected in the `path` option for the plugin.
+As you can see on my system I keep all my markdown files under `content/_posts/`
+which is reflected in the `path` option for the plugin.
-Now restart the dev server and open GraphiQL up again. You should have access to the `allFile` root type. Try running this query:
+Now restart the dev server and open GraphiQL up again. You should have access to
+the `allFile` root type. Try running this query:
```graphql
query {
@@ -173,13 +216,18 @@ query {
}
```
-This will list all the files in the directory you specified to the plugin. You can query all sorts of information about the files. Just investigate the fields available to you under `node` in GraphQL.
+This will list all the files in the directory you specified to the plugin. You
+can query all sorts of information about the files. Just investigate the fields
+available to you under `node` in GraphQL.
-**Pro tip:** Hit ctrlspace to trigger autocomplete and bring up the list of all available fields.
+**Pro tip:** Hit ctrlspace to trigger autocomplete and
+bring up the list of all available fields.
### Handling Markdown
-Being able to query files is a big win, and if you have a directory of HTML files this is all you will need. But if you want to render markdown files as HTML you will need another plugin. Let's add that now:
+Being able to query files is a big win, and if you have a directory of HTML
+files this is all you will need. But if you want to render markdown files as
+HTML you will need another plugin. Let's add that now:
```
yarn add gatsby-transformer-remark
@@ -196,9 +244,13 @@ As before, add it to the `plugins` field in `gatsby-config.js`:
}
```
-This particular plugin can also take _its own_ plugins via the `plugins` option. I've left it empty but this is where you can add things like syntax highlighting or auto-linking of headers. Here's the current list: https://www.npmjs.com/search?q=gatsby-remark
+This particular plugin can also take _its own_ plugins via the `plugins` option.
+I've left it empty but this is where you can add things like syntax highlighting
+or auto-linking of headers. Here's the current list:
+https://www.npmjs.com/search?q=gatsby-remark
-Save and restart your dev server, then go into GraphiQL and try out the new `allMarkdownRemark` field:
+Save and restart your dev server, then go into GraphiQL and try out the new
+`allMarkdownRemark` field:
```graphql
query {
@@ -212,7 +264,9 @@ query {
}
```
-This query gives you the full HTML for all your markdown files. If you are using frontmatter you can also access that here. I'm assuming you have a `title` field in your frontmatter:
+This query gives you the full HTML for all your markdown files. If you are using
+frontmatter you can also access that here. I'm assuming you have a `title` field
+in your frontmatter:
```
query {
@@ -229,24 +283,26 @@ query {
}
```
-Now you have access to the full HTML of your posts as well as the titles. With this we have enough information to render a list of posts on the front page.
+Now you have access to the full HTML of your posts as well as the titles. With
+this we have enough information to render a list of posts on the front page.
### Getting GraphQL data into your components
-Gatsby has the concept of the `pageQuery`. For every page you create you can specify a `pageQuery` that will pass data into the default export of that page.
+Gatsby has the concept of the `pageQuery`. For every page you create you can
+specify a `pageQuery` that will pass data into the default export of that page.
```jsx
// src/pages/index.js
-import React from 'react';
+import React from "react"
export default class BlogIndex extends React.Component {
render() {
// Handle graphql errors
if (this.props.errors && this.props.errors.length) {
this.props.errors.forEach(({ message }) => {
- console.error(`BlogIndex render errr: ${message}`);
- });
- return Errors found: Check the console for details
;
+ console.error(`BlogIndex render errr: ${message}`)
+ })
+ return Errors found: Check the console for details
}
return (
@@ -256,7 +312,7 @@ export default class BlogIndex extends React.Component {
{node.frontmatter.title}
))}
- );
+ )
}
}
@@ -265,31 +321,45 @@ export const pageQuery = graphql`
allMarkdownRemark {
edges {
node {
- frontmatter { title }
+ frontmatter {
+ title
+ }
}
}
}
}
-`;
+`
```
-This is a simplified example, but there are a few things going on that might not be intuitive.
+This is a simplified example, but there are a few things going on that might not
+be intuitive.
-* In the render method we first check for errors, and return early if any are found
-* If no error are found we render a link for each item in the array: `this.props.data.allMarkdownRemark.edges`
-* We export a `pageQuery` variable that is constructed using the magic `graphql` global
+* In the render method we first check for errors, and return early if any are
+ found
+* If no error are found we render a link for each item in the array:
+ `this.props.data.allMarkdownRemark.edges`
+* We export a `pageQuery` variable that is constructed using the magic `graphql`
+ global
-The error handling is pretty straightforward, if a bit verbose, as long as you know what graphql responses look like. In case you didn't know, if you get an error in a graphql query the response will contain the `errors` array. We check for this array and handle it accordingly.
+The error handling is pretty straightforward, if a bit verbose, as long as you
+know what graphql responses look like. In case you didn't know, if you get an
+error in a graphql query the response will contain the `errors` array. We check
+for this array and handle it accordingly.
Now let's looks specifically at where we render a link for each blog post:
```jsx
-{this.props.data.allMarkdownRemark.edges.map(({ node }, i) => (
-
+ ))
+}
```
-Notice that the data shape is exactly what we specified in the GraphQL query. This may seem like a lot of nesting just to get at an array of data, but GraphQL emphasizes _clarity_ over conciseness. You'll notice that if you run your GraphQL query in GraphiQL the data will have the exact shape described above.
+Notice that the data shape is exactly what we specified in the GraphQL query.
+This may seem like a lot of nesting just to get at an array of data, but GraphQL
+emphasizes _clarity_ over conciseness. You'll notice that if you run your
+GraphQL query in GraphiQL the data will have the exact shape described above.
And that brings us finally to the page query:
@@ -299,23 +369,31 @@ export const pageQuery = graphql`
allMarkdownRemark {
edges {
node {
- frontmatter { title }
+ frontmatter {
+ title
+ }
}
}
}
}
-`;
+`
```
-This is how you get data from Gatsby into your react components. Make sure you don't misspell `pageQuery` otherwise you won't get what you want.
+This is how you get data from Gatsby into your react components. Make sure you
+don't misspell `pageQuery` otherwise you won't get what you want.
-Also note that `graphql` is just some magic global variable. Your linter will probably complain about it being undefined and you will just have to ignore it. Personally I think it would be more clear if `graphql` was imported from Gatsby, but the project is still young so the API could change at some point ¯\\\_(ツ)\_/¯
+Also note that `graphql` is just some magic global variable. Your linter will
+probably complain about it being undefined and you will just have to ignore it.
+Personally I think it would be more clear if `graphql` was imported from Gatsby,
+but the project is still young so the API could change at some point ¯\\_( ツ
+)_/¯
### Linking to blog posts
> But the links don't link anywhere... where's that `href`?
-Let's remedy that. Import the `gatsby-link` component and swap it for the simple `