1.1.0 • Published 4 years ago

gatsby-arcadia-starter v1.1.0

Weekly downloads
2
License
MIT
Repository
github
Last release
4 years ago

Arcadia

Netlify Status

Arcadia is a modern, beatiful and customizable starter for Gatsby.

Features

  • Support for Three.js animations.
  • Easy to create and manage MDX sections.
  • GitHub API support to display your pinned repositories.
  • Contact form with Netlify support.
  • Great accessibility & SEO.
  • Google Analytics ready to use.
  • PWA & Offline support.
  • Easy to customize theme using Styled Components.
  • Clear project structure.

Installation

To start using Arcadia run the following commands in your terminal:

git clone <yoursite> https://github.com/danielkvist/gatsby-arcadia-starter
cd <yoursite>
npm install && npm run develop

Note: Arcadia hasn't yet been added to the Gatsby starters gallery, so the command gatsby new <yoursite> github.com/danielkvist/gatsby-arcadia-starter does not work for the moment.

Gatsby config

As you may already know, the main Gatsby configuration file is divided into two sections.

Site Metadata

const siteMetadata = {
  title: "Gatsby Arcadia",
  description: "A modern and awesome starter for Gatsby.",
  author: "@danielkvist",
  email: "yourmail@yourmailprovider.com",
  siteUrl: "https://gatsby-arcadia.netlify.app/",
  netlifyForm: false,
  copy: "",
  externalLinks: [
    {
      name: "Twitter",
      url: "#",
    },
    {
      name: "Facebook",
      url: "#",
    },
    {
      name: "Instagram",
      url: "#",
    },
    {
      name: "Codepen",
      url: "#",
    },
    {
      name: "GitHub",
      url: "#",
    },
    {
      name: "GitLab",
      url: "#",
    },
  ],
}

title and the description values will be used as title and description of the site if the Layout component does not receive other different values.

email value will be showed as a floating link above the footer, in the right-hand corner.

siteUrl is required for the plugin gatsby-plugin-sitemap to work properly.

netlifyForm boolean enables or disable Netlify's form, but not disables the form itself. It just won't work.

copy message will be displayed in the footer, if no copy message is provided an autogenerated one will be showed.

externalLinks is an array of a list of external links that will be showed in the footer.

Plugins

const plugins = [
  "gatsby-plugin-react-helmet",
  {
    resolve: "gatsby-plugin-google-fonts",
    options: {
      fonts: [
        `roboto\:400,600,700`,
        `roboto mono\:400,600,700`,
        `roboto slab\:400,600,700`,
      ],
      display: "swap",
    },
  },
  {
    resolve: "gatsby-plugin-manifest",
    options: {
      name: "gatsby-arcadia-starter",
      short_name: "starter",
      start_url: "/",
      background_color: "#c7166f",
      theme_color: "#c7166f",
      display: "minimal-ui",
      icon: "src/images/arcadia-icon.png",
    },
  },
  "gatsby-plugin-offline",
  "gatsby-plugin-styled-components",
  "gatsby-plugin-sharp",
  "gatsby-remark-images",
  {
    resolve: "gatsby-plugin-mdx",
    options: {
      gatsbyRemarkPlugins: [
        {
          resolve: "gatsby-remark-images",
          options: {
            maxWidth: 1035,
            sizeByPixelDesinity: true,
            remarkPlugins: [emoji],
          },
        },
      ],
    },
  },
  {
    resolve: "gatsby-source-filesystem",
    options: {
      name: "sections",
      path: `${__dirname}/content/sections/`,
    },
  },
  `gatsby-plugin-sitemap`,
  process.env.GITHUB_API_TOKEN && {
    resolve: `gatsby-source-github-api`,
    options: {
      token: `${process.env.GITHUB_API_TOKEN}`,
      variables: {},
      graphQLQuery: `
        query {
          viewer {
            pinnedItems(first: 6) {
              edges {
                node {
                  ... on Repository {
                    id
                    name
                    description
                    url
                  }
                }
              }
            }
          }
        }
        `,
    },
  },
  process.env.GOOGLE_ANALYTICS_KEY && {
    resolve: `gatsby-plugin-google-analytics`,
    options: {
      trackingId: `${process.env.GOOGLE_ANALYTICS_KEY}`,
      head: false,
      anonymize: true,
      respectDNT: true,
      defer: true,
      sampleRate: 5,
      siteSpeedSampleRate: 10,
    },
  },
].filter(Boolean)

Here is a link to the official documentation for each plugin:

To add your GitHub's API token and your Google Analytics key you will need to create the following env variables:

GITHUB_API_TOKEN=YOURGITHUBAPITOKEN
GOOGLE_ANALYTICS_KEY=YOURGOOGLEANALYTICSKEY

If you have any doubts about how to get a personal access token for the GitHub API check this link.

If you don't add a token for Github or a key to Google analytics those plugins won't be used, in the case of GitHub you have to perform a series of steps described here to avoid query errors.

Theme

Arcadia uses a CSS-in-JS library called styled-components which has support for theming. In the case of Arcadia, the theme.js file which define things like font sizes, spacing, line heights and colors can be found into the folder /src/theme.

If you are not going to deeply customize Arcadia, I recommend you to change only the colors.

Unfortunately the theme cannot be applied everywhere. So if, for example, you change the colors used by Arcadia you will also need to update them in the main gatsby configuration file (gatsby-config.js), specifically in the gatsby-plugin-manifest configuration.

MDX sections

Arcadia, by default, looks for the folder /content/sections (this path is customizable) to generate your home sections. You can have as many sections as you want as long as each MDX file has a title and an order specified in the frontmatter.

---
title: Gatsby
order: 2
---

Gatsby is just amazing. Thanks to it and its great number of available plugins Arcadia has offline support among many other things. If you're not familiar with Gatsby don't worry, It's a really well documented project with a fantastic community.

If you want to know more about what MDX is check the official documentation here or this page about Gatsby and MDX.

GitHub sections

This starter is intended to be used as portfolio for a developer. That's why I decided to add a section to showcase your most important repositories on GitHub.

If you don't want to display your pinned repositories you can remove the functional component home-repositories.js from your index.js page and remove the home-repositories.js component file. If you don't specify a GITHUB_API_TOKEN env variable the gatsby-source-github-api will not be used.

If you're looking for or need support for GitLab, I'm sorry to say that at the moment I have no plans to add it as an alternative, although this may change in the future. I have nothing against GitLab, this is for practical reasons.

Contact form

Arcadia uses react-hook-forms to manage the contact form. By default it comes with a field for a name, a contact email and a message. To modify this contact form to add or remove fields you will need to modify the functional component home-form.js.

For the moment it only works with Netlify forms, so if you disable the netlifyForm option in the gatsby-config.js file the form won't work.

To avoid bots or spam, once a message has been sent the form will disappear to display a "thank you!" message.

Footer

The footer in Arcadia only shows the contact email, a list of links for your social networks and a copyright message. To change any of these values you can go and modify the gatsby-config.js file as explained above.

Cypress E2E Testing

Arcadia also comes with Cypress installed and ready to use. If you want to learn more about using Cypress with Gatsby check this link from the official Gatsby documentation.

Help is always welcome!

If you have ideas to make Arcadia a better project or you detect any errors please do not hesitate to let me know either by sending a PR or by opening an issue!

In the future

In the future I would like:

  • Convert Arcadia into a Gatsby theme.
  • Add support for blogging.
  • Add support for multiple languages.