README
Arcadia - Gatsby Theme
Arcadia is a modern, fast, beatiful and customizable theme for Gatsby.
Features
- Easy to update thanks to Gatsby themes.
- Easy customization thanks to shadowing in Gatsby themes.
- Easy to customize theme using Styled Components.
- Support for Three.js animations.
- Easy to create and manage MDX sections.
- GitHub API support to display your pinned repositories.
- Codepen section to showcase your pens.
- Contact form with Netlify support.
- Great accessibility & SEO.
- Clear project structure.
If you would like to use Arcadia but you are looking for something more minimalist I recommend you to check the Arcadia light version.
Installation
To install Arcadia run:
npm install gatsby-theme-arcadia
// Or
yarn add gatsby-theme-arcadia
Arcadia needs to receive two options:
sectionsPath: directory to home sections content.githubToken: GitHub access token to get your repositories data.
const plugins = [
{
resolve: "gatsby-theme-arcadia",
options: {
sectionsPath: `${__dirname}/content/sections`,
githubToken: `${process.env.GITHUB_API_TOKEN}`,
},
},
]
Gatsby config
As you may already know, the main Gatsby configuration file is divided into two sections.
Default Site Metadata
const path = require("path")
require("dotenv").config({
path: `../.env.${process.env.NODE_ENV}`,
})
const siteMetadata = {
title: "Arcadia",
description: "A modern and awesome theme for Gatsby to show your work.",
author: "@danielkvist_",
email: "yourmail@yourmailprovider.com",
siteUrl: "https://gatsby-arcadia.netlify.app/",
netlifyForm: false,
copy: "",
seo: {
title: "Gatsby Arcadia Theme",
description:
"A modern and awesome theme for Gatsby designed for web developers and with accessibility, performance and customization in mind.",
},
codepen: [
{
name: "React Calculator",
description: "A short description.",
image: "calculator.png",
url: "#",
},
{
name: "React Calendar Component",
description: "A short description.",
image: "calendar.png",
url: "#",
},
{
name: "Magic Bonfire",
description: "A short description.",
image: "magic-bonfire.png",
url: "#",
},
{
name: "React Markdown Editor",
description: "A short description.",
image: "markdown.png",
url: "#",
},
{
name: "Pomodoro w/ React Context",
description: "A short description.",
image: "pomodoro.png",
url: "#",
},
{
name: "Sign in/Sing Up form",
description: "A short description.",
image: "signin-singup.jpg",
url: "#",
},
],
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.
seo title, description username for SEO. If the title and description properties are not defined, the site title and description will be used.
codepen is an array with a list of pens that will be showed in the Codepen's showcase section, under your GitHub's section. The images used should be compressed before using them.
externalLinks is another array of external links that will be showed in the footer.
Plugins
const plugins = (sectionsPath, githubToken) => [
"gatsby-plugin-react-helmet",
"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: sectionsPath,
},
},
{
resolve: `gatsby-source-github-api`,
options: {
token: githubToken,
variables: {},
graphQLQuery: `
query {
viewer {
pinnedItems(first: 6) {
edges {
node {
... on Repository {
id
name
description
url
}
}
}
}
}
}
`,
},
},
]
Here is a link to the official documentation for each plugin:
- gatsby-plugin-react-helmet.
- gatsby-plugin-styled-components.
- gatsby-plugin-sharp.
- gatsby-remark-images.
- gatsby-plugin-mdx.
- gatsby-source-filesystem.
- gatsby-source-github-api.
If you have any doubts about how to get a personal access token for the GitHub API check this link.
Theme
Arcadia uses a CSS-in-JS library called styled-components which has support for theming. So if for example you want to change the default fonts used you can overwrite the fonts.js in the theme folder using shadowing.
// Inside your project in src/gatsby-theme-arcadia/theme/fonts.js
const fonts = {
default: "Roboto, sans-serif",
title: "'Roboto Slab', serif",
}
export default fonts
You can do the same thing for:
- The color palette.
- Font sizes.
- Font weight.
- Font family.
- Line heights.
- Media queries.
- Spacing.
- Transitions.
If you are not going to deeply customize Arcadia, I recommend you to change only the colors and fonts. Also, to load Google Fonts I recommend to use the gatsby-plugin-google-fonts plugin.
If you change the colors used by Arcadia remember to also update them in the main gatsby configuration file (gatsby-config.js), specifically in the gatsby-plugin-manifest configuration if you are using it.
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.
Note: every section in Arcadia will have an ID based on their title in case you want to add a navigation menu later.
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.
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 multiple languages.