Update: this repo is outdated, so I wouldn't recommend it. Look at the official Gatsby quickstart instead.
Everything you need for a basic website + blog with Gatsby.js. (preview)
Requirements: Node 12.13.0 or above.
This has been updated to Gatsby 3. If you notice any bugs with this new Gatsby 3 version, please open a pull request. The migration docs are here.
It uses TypeScript now. TypeScript is JavaScript with a few extra features that help reduce bugs. You can write plain JavaScript if you want, even though the files have .tsx extensions.
If you haven't used TypeScript before, check out the getting started guide and Learn TypeScript in Y Minutes. The Gatsby docs also have a page about using TypeScript with Gatsby.
To customize the TypeScript configuration, see this page.
$ gatsby new project_name https://github.com/j127/gatsby-starter-website-blog
Then edit your new site.
Install Gatsby CLI:
$ npm install -g gatsby-cli
Disable telemetry:
Set an environment variable in your shell config file like this:
export GATSBY_TELEMETRY_DISABLED=1
and/or run gatsby telemetry --disable in a terminal window.
Start a new project, changing project_name to the desired name of your app:
$ gatsby new project_name https://github.com/j127/gatsby-starter-website-blog
Then cd into the project directory and start coding.
This starter comes with a nice CSS framework called Bulma. PurgeCSS is used to remove all the unused CSS rules, so it's really fast and efficient.
But if you want to remove Bulma, run this command:
$ npm uninstall -S bulma
Then search the files for any mention of "bulma" and delete those imports.
Override Bulma variables in the src/styles/_variables.scss file. See the notes in the files in the src/styles directory.
The markdown in blog posts uses MDX. It's markdown with JSX.
If you need a responsive table in a blog post (written with markdown), wrap the markdown table with a table-container div like this:
<div class="table-container">
<!-- table markdown goes here, padded with empty lines above and below -->
</div>
Jest and Cypress are installed. See the how to write tests section of the documentation.
Write tests in the cypress directory (see the included examples). Run the tests with:
$ npm run cy:open
See this page for more information.
See the Gatsby/Jest docs. There's also a page on testing React components.
Sourcemaps are removed by default (see here). If you want to add sourcemaps in production, then remove the gatsby-plugin-no-sourcemaps plugin from gatsby-config.js file.
To make it easier to create new blog posts, there is a generator script named g.
To use it, make sure you have Ruby and bundler installed.
$ bundle install
(If bundler isn't installed, you can install it with gem install bundler and then try running bundle install again.)
Look in the g script for the line that looks like this:
AUTHOR = '' || ENV["USER"]Put your author name inside the single quotes.
You can now generate skeletons for new blog posts by running this command:
$ ./g new 'This Is the Title of a Blog Post'
Out of the box, this template comes with an RSS feed for the blog at /rss.xml. To add additional RSS feeds, see the docs.
The code can be auto-formatted with Prettier.js. Just type the command npm run format or have your editor auto-format with prettier on save. To change the code style, edit the files .prettierrc and .editorconfig. (Search online to see how to use those files, if you aren't familiar with them.)
This kind of site can be deployed on Netlify using their Github connector or with the Netlify CLI. For example, the demo site for this theme is deployed with this command:
$ npm run build && netlify deploy --prod --dir=public
If you want to deploy to Netlify, there are already stage and deploy scripts in the package.json file. Just read about the Netlify CLI above, preview the live site with npm run stage, and deploy with npm run deploy.