Gatsby

Transform plain text into dynamic blogs and websites using the latest web technologies. A React.js static site generator.

Supports Markdown, HTML, and React.js pages out of the box. Easy to add support for additional file types.

Leverages React's component model and React Router's "nested component hierarchy" to make templating incredibly powerful and intuitive.

All templates, css, and content are hot reloadable — powered by webpack.

Build sites like it's 1995. Files are translated into HTML pages at the same position within the file system. Add a markdown file at /docs/index.md and it'll be converted to /docs/index.html.

We've started work on a 1.0 release of Gatsby! Find the code in the 1.0 branch.

Checkout the first 1.0 example site GatsbyGram https://gatsbygram.netlify.com

Goals

No-reload page transitions
Hot reload editing. Tweak your pages, templates, and styles and see changes in real time.
Make React.js component model and ecosystem available for building static sites
Intuitive directory-based URLs. The URL of a page is derived from its spot on the file system.
Support "Starters" — install starter sites directly from Github. Use open sourced starters or build your own.

Why use Gatsby instead of other Static Site Generators

No-refresh page transitions
The awesome React.js component model
Live editing on every part of your site. Dramatically speed development.

Sites built with Gatsby

Note, for the sites that have made their source available, you can install them locally by running gatsby new SITE_NAME SOURCE_URL.

Videos and blogs

Scott Nonnenberg presents on Gatsby to the Seattle React.js Meetup https://blog.scottnonnenberg.com/static-site-generation-with-gatsby-js/
Kyle Mathews gave a lightning talk @ the 2016 React.js Conference on Gatsby https://www.youtube.com/watch?v=RFkNRKL6ZoE
Kyle Mathews spoke on Gatsby to the San Francisco Static Web Tech meetup http://www.staticwebtech.com/presentations/developing-with-react-gatsbyjs/
ReactJS E-Commerce With No Backend Using Snipcart & Gatsby
A step-by-step guide: Gatsby on Netlify
Hosting GatsbyJS – A React Static Site Generator
Michael Cereda's multi-part series of blog posts on building his site with Gatsby
Talk on GatsbyJS @ ViennaJS

I'm already building a server-rendered React.js site, is Gatsby a good fit?

If your site falls closer to the site end of the app<---->site spectrum then yes.

Gatsby is an excellent fit for blogs, marketing sites, docs sites, etc. Proper web apps should probably remain as normal web apps (though I'd love to be proved wrong!).

Warning!

Gatsby is not yet stable. APIs will break. Functionality is missing. It's usable but if you plan on building with it, expect a rocky road for some time.

Contributions welcome!

Getting started

Install

npm install -g gatsby

Usage

Create new Gatsby site gatsby new my-test-gatsby-site This creates the directory for your Gatsby project and adds the minimal files needed.
cd my-test-gatsby-site
gatsby develop — Gatsby will start a hot-reloading development server accessible at localhost:8000
See the tutorial below for more.

Gatsby Starters

The Gatsby CLI tool lets you install "starters". These are partially built sites preconfigured to help you get moving faster on creating a certain type of site.

When creating a new site, you can optionally specify a starter to base your new site on e.g. gatsby new [SITE_DIRECTORY] [URL_OF_STARTER]

For example, to quickly create a blog using Gatsby, you could install the Gatsby Starter Blog by running:

gatsby new blog https://github.com/gatsbyjs/gatsby-starter-blog

This downloads the files and initializes the site by running npm install

If you don't specify a custom starter, your site will be created from the default starter.

There are several starters that have been created. Create a PR to include yours!

Tutorial: Building a documentation site from the Gatsby Documentation Starter

Install gatsby npm install -g gatsby
Install documentation site starter gatsby new docs-site gh:gatsbyjs/gatsby-starter-documentation
type cd docs-site
type gatsby develop
Open site in browser at localhost:8000. Verify clicking on links works.
Try editing the site's config file config.toml. Change the siteTitle key. The site's title should change shortly after saving.
Next try editing a doc page. Open /pages/docs/getting-started/index.md and edit it. Again any saved changes should load without refreshing in the browser.
Add a new markdown page to the documentation. Copy the getting-started directory to some-additional-steps. Then edit the markdown file within the new directory. If you're familiar with other static site generation software, you'll be familiar with the "frontmatter" at the top of the file. Edit the title there + change the order to "5". Save this. Ideally this new file would be hot reloaded like other changes but I haven't figured out how to make this happen yet (help appreciated here). So to see your new page, restart gatsby develop and then refresh your browser.
Build your site gatsby build. The site is built to the /public directory. Test that the build worked by running gatsby serve-build which serves the contents of the /public directory.

How Gatsby works

How files become pages

The process is file --> Webpack loader --> React.js wrapper component --> static HTML page.

Gatsby leverages Webpack extensively. Webpack is a sophisticated module bundler that can turn any sort of file into a commonjs module. Webpack uses "Loaders" to convert a file into a module. These loaded modules are then wrapped inside a React.js component that's specific to a given file type. Gatsby then generates a static HTML page from this component.

Gatsby ships with default loaders and wrappers for HTML, Markdown, and JSX/CJSX but for most projects you'll want to write your own loaders and wrappers (very easy to do).

As an example of how this process works, let's walk quickly through converting a markdown file into an HTML page.

The default Gatsby markdown loader parses the markdown into HTML and uses Highlight.js to syntax highlight code blocks.

Our markdown file.

---
title: This is a title
---

# Hi friends.
This is a markdown file.

When loaded and required, the resulting javascript object looks like the following:

{
  file: {
    // Information about file on disk e.g. extension, directory path, etc.
  },
  data: {
    title: "This is a title",
    body: "<h1>Hi friends.</h1><p>This is a markdown file</p>"
  }
}

Now Gatsby wraps the markdown file in this very simple React.js component.

module.exports = React.createClass({
  displayName: "MarkdownWrapper",

  render: function() {
    var post = this.props.route.page.data

    return <div className="markdown">
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{__html: post.body}}/>
    </div>
  }
})

frontmatter and metadata

Gatsby uses frontmatter and html-frontmatter to pull metadata out of files. This data is typically used in links leading to each page. The most relevant example is a list of blog posts in which you display the title, description, tags, etc. in the form of {post.title} in the React.js component.

As seen in our previous markdown file, the title is part of the frontmatter

---
title: This is a title
---

# Hi friends.
This is a markdown file.

An html example as follows.

<!--
title: This is a title
-->

<h1>Hello World</h1>

In a .js|.jsx file, export a data object to set your metadata variables, like so:

import React from 'react'

exports.data = {
  title: 'This is a title',
}

export default MyComponent ...

Structure of a Gatsby site

config.toml - Core application configuration is stored here. Available via a require or import of 'config'. Values:
- noProductionJavascript - set to a truthy value to prevent generation of bundle.js (containing your client-side Single Page App) during a gatbsy build. You'll need to update your top-level html.js file so that it doesn't pull in bundle.js in production, but you'll want to keep it for gatsby develop mode.
/pages - All pages go here. Everything is turned into a page except files which start with an underscore:
- _template files under /pages are treated as parent templates for other pages in the same directory tree.
- (optional) pages/404.js or pages/404.html - automatically picked up as your 'not found' page. If you <Link> to an unknown URL, this page will be shown. Note: in production, you'll need to set up your server host to show this page when it can't find the requested file.
(optional) gatsby-browser.js - a way to hook into key application events.
- Export onRouteUpdate of type function() to be notified whenever React-Router navigates.
- Export modifyRoutes of type function(routes: Object) => Object to modify the react-router routes.
- Export shouldUpdateScroll of type function(prevRouterProps: Object, nextRouterProps: Object) => boolean to determine if a given route change should scroll.
(optional) gatsby-node.js - a way to hook into events during build and development.

How to use your own webpack loaders

Gatsby uses webpack-configurator to make changing the webpack loaders easy. The default set of loaders is organized by key.

To modify the Webpack configuration, create a gatsby-node.js in the root of your project and export there a modifyWebpackConfig function.

exports.modifyWebpackConfig = function(config, stage) {
  // edit loaders here
  return config
}

Gatsby calls this function with the webpack-configurator object and "stage" string when it creates a Webpack config. It first loads the defaults and then allows you to modify it.

The stage can be:

develop: for gatsby develop command, hot reload and CSS injection into page
develop-html: same as develop without react-hmre in the babel config for html renderer
build-css: build styles.css file
build-html: build all HTML files
build-javascript: Build bundle.js for Single Page App in production

Consider the following example which removes the default css loader and replaces it with a loader that uses css-modules.

exports.modifyWebpackConfig = function(config, stage) {
  config.removeLoader('css')
  config.loader('css', function(cfg) {
    cfg.test = /\.css$/
    cfg.loader = 'style!css?modules'
    return cfg
  })
  return config
}

Each loader (cfg in the above example) can be a valid webpack loader and there are a host of preexisting loaders which you can use to enhance Gatsby.

It is also possible to write your own loaders.

Gatsby includes some default loaders that you can also override.

To write your own loader or override a Gatsby loader, make a loaders directory at the root of your site that contains directories for custom loaders.

e.g. loaders/markdown-loader/index.js will take precedence over the markdown-loader that Gatsby includes.

See an example of a custom loader in the default starter.

How to use your own webpack plugins

Similar to the loaders, plugins are handled via webpack-configurator and gatsby-node.js.

Note: the following example is now redundant since ExtractTextWebpackPlugin is now setup by default but you can still use it as an example of how to modify the Webpack plugins.

If we wanted to extract all of the css in our project into a since styles.css file for production, we could add the ExtractTextWebpackPlugin. To do this, we need to modify the loader and add the plugin when generating the static HTML for our site.

var ExtractTextPlugin = require("extract-text-webpack-plugin")

exports.modifyWebpackConfig = function(config, stage) {
  if(stage === 'build-html') {
    config.removeLoader('css')
    config.loader('css', function(cfg) {
      cfg.test = /\.css$/
      cfg.loader = ExtractTextPlugin.extract('css?minimize')
      return cfg
    })
    config.plugin('extract-css',
                  ExtractTextPlugin,
                  ["styles.css", { allChunks: true }])
  }
  return config
}

Each plugin (extract-css in the above example) can be a valid webpack plugin and there are a host of preexisting plugins which you can use to enhance Gatsby.

It is also possible to write your own plugins.

Perform additional post build step

Gatsby also uses gatsby-node.js to pass control of the final build step over to the user when running gatsby build. The post build function takes two arguments, the pages and the callback for completing the build:

exports.postBuild = function(pages, callback) {
  // perform actions on pages here

  callback()
}

How to write your own wrappers

Coming...

FAQ

Pre-Requisites

Python v2 is required to install Gatsby. Please ensure python is in your path before running npm install -g gatsby.

I added a new page and it's not showing up!

Webpack doesn't currently support hot-reloading new files added to a context. When you add a new file, restart the gatsby develop process and your new page will show up.

Make sure you also including the trailing slash in your URLs:

Bad: http://localhost:8000/foo
Good: http://localhost:8000/foo/

Inline CSS

A neat performance feature supported by Gatsby is inlining your CSS in the <head> of each HTML page. Not referencing external style sheets significantly speeds up the initial render of your site by avoiding another round trip to your server as the initial render of a page is blocked by external CSS files. This is a best practice suggested by many groups including Google's AMP project.

Each of the official starters supports this pattern. The code to make it happen is in brief:

// In your html.js
let css
// In development, css is injected by Javascript by the Webpack style-loader.
if (process.env.NODE_ENV === 'production') {
  css = <style dangerouslySetInnerHTML={{ __html: require('!raw!./public/styles.css') }} />
}

// Then in your <head>
{css}

CSS modules

CSS modules are supported by default for all files with .module.(css|less|scss|sass) extension.

// Uses CSS Modules
import './my-component.module.css'

// Doesn't use CSS Modules
import './main.css'

Configuring Babel

You can modify Babel's behavior as normal by either providing a .babelrc in your site's root directory or by adding a "babel" section in your site's package.json. You can find out more about how to configure babel here.

Gatsby by default will use your Babel configuration over the default if it can find it. Gatsby will automatically add react-hmre to your Babel config during development.

Note that if you want to use babel-plugin that is not provided by Gatsby, you will have to also add it to your package.json. You can use any babel-plugin that Gatsby packs as a dependency without having to add it to your own package.json:

babel-plugin-add-module-exports
babel-plugin-transform-object-assign
babel-preset-es2015
babel-preset-react
babel-preset-stage-0

If you need to change the loader to be something completely custom. You will have to define your own webpack loader by following the steps described above.

Extending Markdown Syntax with Plugins

Gatsby uses markdown-it to parse markdown files into HTML. By default Gatsy ships with only basic markdown support. You can extend the syntax (e.g. for mathematical equations) by installing markdown-it plugins.

If you want to do this you will need to use a custom markdown loader. You can copy the one provided in the default starter here. Add the relevant packages to your dependencies, including the markdown-it plugins that you want to use and enable them with md.use(require('markdown-it-plugin-name')) within the markdown loader file.

Deploying to Github Pages (and other hosts where your site's links need prefixes)

Gatsby supports automatically prefixing links with its prefixLink helper function.

First set the prefix in your config file e.g. linkPrefix = '/your-project'

Then simply import the function and run all links in your site through it e.g.

import { prefixLink } from 'gatsby-helpers'

prefixLink('/')
// During development this will return "/"
// When deployed to example.github.io/your-project/ this will return "/your-project/"

Then finally, when building your site, run gatsby build --prefix-links

The built site is now in /public. These files need copied to your gh-pages branch and committed and pushed. You can do this manually or use the handy gh-pages CLI tool.

Both the sample sites are deployed to github pages and use link prefixing. Read their source for more help: documentation/blog.

I have an existing site in (Wordpress|Drupal|Blogger|Tumblr|*), how do I convert it to Gatsby?

Jekyll has a comprehensive import tool for these and many other website tools. Once your pages are converted to markdown, change the file extensions to .md from the .markdown the tool outputs and then use them in your site.

Backers

Support us with a monthly donation and help us continue our activities. [Become a backer]

Name		Name	Last commit message	Last commit date
Latest commit History 726 Commits
bin		bin
docs		docs
interfaces		interfaces
lib		lib
scripts		scripts
test		test
.babelrc		.babelrc
.codeclimate.yml		.codeclimate.yml
.eslintignore		.eslintignore
.eslintrc		.eslintrc
.flowconfig		.flowconfig
.gitignore		.gitignore
.npmignore		.npmignore
.publishrc		.publishrc
.travis.yml		.travis.yml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
yarn.lock		yarn.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Gatsby

Goals

Why use Gatsby instead of other Static Site Generators

Sites built with Gatsby

Sponsors

Videos and blogs

I'm already building a server-rendered React.js site, is Gatsby a good fit?

Warning!

Getting started

Install

Usage

Gatsby Starters

Tutorial: Building a documentation site from the Gatsby Documentation Starter

How Gatsby works

How files become pages

frontmatter and metadata

Structure of a Gatsby site

How to use your own webpack loaders

How to use your own webpack plugins

Perform additional post build step

How to write your own wrappers

FAQ

Pre-Requisites

I added a new page and it's not showing up!

Inline CSS

CSS modules

Configuring Babel

Extending Markdown Syntax with Plugins

Deploying to Github Pages (and other hosts where your site's links need prefixes)

I have an existing site in (Wordpress|Drupal|Blogger|Tumblr|*), how do I convert it to Gatsby?

Backers

Sponsors

About

Releases

Packages

Languages

License

danielres/gatsby

Folders and files

Latest commit

History

Repository files navigation

Gatsby

Goals

Why use Gatsby instead of other Static Site Generators

Sites built with Gatsby

Sponsors

Videos and blogs

I'm already building a server-rendered React.js site, is Gatsby a good fit?

Warning!

Getting started

Install

Usage

Gatsby Starters

Tutorial: Building a documentation site from the Gatsby Documentation Starter

How Gatsby works

How files become pages

frontmatter and metadata

Structure of a Gatsby site

How to use your own webpack loaders

How to use your own webpack plugins

Perform additional post build step

How to write your own wrappers

FAQ

Pre-Requisites

I added a new page and it's not showing up!

Inline CSS

CSS modules

Configuring Babel

Extending Markdown Syntax with Plugins

Deploying to Github Pages (and other hosts where your site's links need prefixes)

I have an existing site in (Wordpress|Drupal|Blogger|Tumblr|*), how do I convert it to Gatsby?

Backers

Sponsors

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages