Gatsby Advanced Starter

A starter skeleton with advanced features for Gatsby.

This starter aims to provide a minimal base for building advanced GatsbyJS powered websites by using the latest technologies to simplify your process.

It doesn't define any UI limitations in any way and only gives you the basic components for SEO/Links/Infinite Scrolling while creating a comfortable development environment to get started.

Starter supports both TypeScript and JavaScript, comes with Jest and Cypress configurations and allows you to write Unit/Integration/E2E tests out of the box.

You are free to use any UI framework/styling options or you can use the gatsby-theme-amaranth as a starting point, which provides a stylish blog design styled with Styled Components

Demos

With gatsby-theme-advanced

With gatsby-theme-amaranth.

Features

Gatsby v4 support
First class TypeScript support (for query data and components exposed by the theme)
Styled Components used for styling
Posts in MDX
- Code syntax highlighting
- Embed videos
- Embed iframes
Infinite Scrolling
React Query for client side API calls
Tags
- Separate page for posts under each tag
Categories
- Separate page for posts under each category
Social features
- Twitter tweet button
- Facebook share/share count
- Reddit share/share count
- LinkedIn share button
Author section
Related posts computation and display based on category/tag match ranking
Disqus support
gatsby-plugin-image for optimized image generation
Inline SVG imports
High configurability
Separate components for everything:
- Gatsby Link utilities
- SEO
- Disqus
PWA features
- Offline support
- Web App Manifest support
- Loading progress for slow networks
SEO
- Google gtag.js support
- Sitemap generation
- General description tags
- Google Structured Data
- OpenGraph Tags (Facebook/Google+/Pinterest)
- Twitter Tags (Twitter Cards)
RSS feeds
Development tools
- Yarn 3
- Jest for unit/integration testing
- Cypress for E2E testing
- CI via GitHub Actions
- CD via GitHub Actions
- ESLint for linting
- Prettier for code formatting
- React Hooks Linting
- Remark-Lint for linting Markdown
- write-good for linting English prose
- gh-pages for deploying to GitHub pages
- Netlify deploy configuration

Getting Started

Install this starter by running the following commands from your CLI:

gatsby new YourProjectName https://github.com/Vagr9K/gatsby-advanced-starter
cd YourProjectName
yarn develop # or gatsby develop

Note that the Gatsby CLI needs to be installed and updated for the gatsby command to work.

Alternatively you can fork the project, make your changes and merge new upstream features when needed:

Fork this repository on GitHub

Run the following commands:

git clone https://github.com/${YourUsername}/${YourForkName} YourForkName # Clone your fork
cd YourForkName
yarn install # or npm install
yarn develop # or gatsby develop

Receiving upstream updates

You have multiple options when it comes to receiving upstream updates:

Pull and merge upstream changes into your repo
Change the versions of gatsby-theme-advanced and gatsby-theme-amaranth from local to remote.
Install a different theme, such as the gatsby-theme-material.

First option allows you to make your own changes to the themes without having to fork and publish them. This is the default approach when you clone/fork the starter repository.

Second option simplifies your CI/CD setup and allows you to receive updates by simply bumping the package version. This also applies if you decide to use a different theme with the starter.

To switch to the remote versions, open package.json and edit the dependency section:

 "gatsby-theme-amaranth": "*",
 // or
  "gatsby-theme-advanced": "*",

into

 "gatsby-theme-amaranth": "3.2", // Or the version you want
 // or
  "gatsby-theme-advanced": "3.2", // Or the version you want

If you want to install a different theme outside of the repo, such as the gatsby-theme-material, run:

yarn add gatsby-theme-material # Or any other Gatsby theme

Then configure the theme in gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-material`, // Or any other theme that you have installed
      options: {
        basePath: `/blog`, // Consult the documentation of the respective theme to figure out the applicable settings
      },
    },
  ],
};

Configuration

Select a starting point

To configure the theme edit your gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-theme-advanced`,
      options: {
        basePath: `/blog`,
      },
    },
  ],
};

Here you can switch between gatsby-theme-advanced and gatsby-theme-amaranth or any other Gatsby theme that you intend to use with the starter.

For configuring the themes, consult their respective documentation pages:

NetlifyCMS

First of all, make sure to edit static/admin/config.yml and add your GitHub/GitLab/NetlifyId credentials:

backend:
  name: github # Refer to https://www.netlifycms.org/docs/authentication-backends/ for auth backend list and instructions
  branch: master # Branch to update
  repo: vagr9k/gatsby-material-starter # Repo for pushing new commits. Make sure to replace with your repo!

You can visit /admin/ after and will be greeted by a login dialog (depending on the auth provider you ave chosen above).

If want to customize Netlify CMS, e.g. registering custom widgets or styling the preview pane, you can do so by editing src/netlifycms/index.js:

import CMS from "netlify-cms-app";

CMS.init({
  config: {
    backend: {
      name: "git-gateway",
    },
  },
});

For NetlifyCMS specific issues visit the official documentation.

Contributing

If you have any issues, questions or suggestions related to the starter then feel free to bring them up!

If you'd like to contribute to the repository and need some pointers, take a look at the Contribution Guide.

Author

Ruben Harutyunyan (@Vagr9K)

almeidacavalcante/almeidacavalcante-blog