@leontastic/gatsby
Advanced tools
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 files 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!
Note, for the sites that have made their source available, you can
install them locally by running gatsby new SITE_NAME SOURCE_URL.
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!).
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!
npm install -g gatsby
gatsby new my-test-gatsby-site This creates the
directory for your Gatsby project and adds the minimal files
needed.cd my-test-gatsby-sitegatsby develop — Gatsby will start a hot-reloading development
server accessible at localhost:8000The 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!
npm install -g gatsbygatsby new docs-site gh:gatsbyjs/gatsby-starter-documentationcd docs-sitegatsby developconfig.toml.
Change the siteTitle key. The site's title should change shortly
after saving./pages/docs/getting-started/index.md and edit it. Again any saved
changes should load without refreshing in the browser.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.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.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>
}
})
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.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.gatsby-browser.js - a way to hook into key application events. Export
onRouteUpdate of type function() to be notified whenever React-Router
navigates.gatsby-node.js - a way to hook into events during build
and development.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, env) {
// edit loaders here
return config
}
Gatsby calls this function with the webpack-configurator object and environment string when it creates a Webpack config. It first loads the defaults and then allows you to modify it.
The env can be
develop (when running gatsby develop)static (when Gatsby is building static HTML pages)production (when Gatsby is generating the CSS/JS bundles)Consider the following example which removes the default css loader and replaces it with a loader that uses css-modules.
exports.modifyWebpackConfig = function(config, env) {
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.
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, env) {
if(env === 'static') {
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.
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:
export.postBuild = function(pages, callback) {
// perform actions on pages here
callback()
}
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:
http://localhost:8000/foohttp://localhost:8000/foo/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 are support 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'
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:
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.
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 thorough 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.
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.
FAQs
React.js Static Site Generator
We found that @leontastic/gatsby demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."