Gatsby - freeCodeCamp.org

Learn Gatsby, a Static Site Generator

Beau Carnes — Thu, 16 Sep 2021 15:34:47 +0000

Gatsby is a website generator. It is a free and open source framework based on React that helps developers build fast websites and apps.

We just published a 9-hour Gatsby course on the freeCodeCamp.org YouTube channel that will teach you how to use the newest version of the framework.

Here's to learning Gatsby.

During this course, you will learn how to create and deploy an interactive recipe website.

The course contains the following sections:

Gatsby Info
Course Structure
Course Requirements
Vs Code
Module Intro
Install Gatsby-Cli
Setup New Gatsby Project
Folder Structure
First Page
Error Page
Nested Structure
Links
Navbar
Layout Component
CSS Module Intro
Inline CSS
Global CSS
CSS Naming Issues
CSS Modules
Styled-Components
House Cleaning
Styles
Footer
Error Page
Contact Page
Assets And Icons
Navbar Setup
Navbar Logic
Gatsby Image Info
Sandbox Setup
Install Plugin
Static Image Setup
Shared Props And Options
Options Example
All Layouts
Height
About Page
Hero Page
Gatsby And GraphQL Intro
Gatsby DataLayer In A Nutshell
GraphiQL Interface
SiteMetadata
First Query
Explorer
Static Query Vs Page Query
UseStaticQuery Hook - Code Exporter
UseStaticQuery, GraphQL - From Scratch
Field Alias
Query Keyword, Name And Gatsby Clean
Page Query
Install SOURCE-FILESYSTEM Plugin
AllFile Field
Query Arguments
Static Path Fix
File - Field
SourceInstanceName - Argument
Gallery Setup
GatsbyImageData - Field
Render Gallery
GetImage - Helper Function
Local VS External Data
Headless CMS
Contentful
Setup Contentful Account
Content-Type
Content
Connect Gatsby - Contentful
ENV Variables
AllContentfulRecipe - Field
AllRecipes Component
RecipesList Component
Featured Recipes
Utils Setup
Helper Function
TagsList
Tags Page
Recipe Template Page Setup
Recipe Template Page Walkthrough
Slugify
Query Variables
Recipe Template Query
Recipe Template Return
GATSBY-NODE.JS Setup
Create Tag Pages Programmatically
Tag Template Return
Possible Bug Fix
Fonts
Contact Form
FAVICON
SEO Setup
SEO - Props
SEO - Complete
Netlify Info
Netlify - Drag And Drop
Continuous Deployment
Webhooks

Watch the full course below or on the freeCodeCamp.org YouTube channel (9-hour watch).

How to Use Webmentions with Gatsby.js – A Beginner's Guide

Spruce Emmanuel — Thu, 22 Jul 2021 16:33:55 +0000

Webmention is a simple protocol developed by the IndieWeb Community that you can use to request notifications when your URLs are mentioned on the web.

When you post on your own site and syndicate elsewhere (POSSE), Webmention lets you enable rich interactions on your syndicated posts. This article will walk you through the simplest way to turn your social media interactions into Webmentions and display them on your Gatsby.js site.

This tutorial will implement Webmentions on an already existing site, so you should have at least some basic knowledge of React and Gatsby.

Getting Started

To help you better understand how Webmentions work, check out the image below:

Different stages of Webmention process

Let's break down this these three stages and learn how to implement them.

How to Send Webmentions

A Webmention Sender is an implementation that send's Webmentions. Bridgy is a good example of a sender.

Bridgy is an open source tool that pulls your social media interactions from popular social sites and blog engines like Twitter, Facebook, Instagram, and Medium and magically turns them into Webmentions.

Bridgy turning social interactions to Webmentions

To use Bridgy, your domain needs to support the indieAuth Login process.

In your layout.js component (or from whatever component you are managing your with React Helmet), add the following code to link to your social profiles:

import { Helmet } from "react-helmet"
// other imports

export default function Layout({ children}) {

  return (
    <div className="wrapper">
      <Helmet>

        <link rel="me" href="https://twitter.com/sprucekhalifa" />
        <link rel="me" href="https://github.com/iamspruce" />

      Helmet>
...
    div>
  )
}

On each of the social services you just linked to, make sure your profile has a link leading back to your homepage like you can see below:

Adding a link back to you homepage on Twitter

That's it! You are done with the IndieAuth login Process. Now head over to Bridgy and sign in with Twitter (if you used Twitter for your IndieAuth process).

From now on Bridgy will periodically analyze your tweets (I promise it doesn't do anything with your data). For each tweet that has a link to your site, it will get all the replies, likes, retweets, and so on and send them as Webmentions.

How to Receive Webmentions

A Webmention receiver is an implementation that receives Webmentions to one or more target URLs.

This implementation can be a script executed on your server, but in the case of GatsbyJs which has no server we'll rely on a third party tool called webmention.io created by Aaron Parecki.

This Tool receives your Webmentions and stores and organizes them. It also provides an API that you can use to easily grab your Webmentions and display them on your site.

To use webmention.io make sure you followed the IndieAuth Login process in the "How to Send Webmentions" section. Then go to webmention.io and sign in with your domain name.

Once you have signed up, add the following to the of your site (and just replace username with the username you got when you logged in):

import { Helmet } from "react-helmet"
// other imports

export default function Layout({ children}) {

  return (
    <div className="wrapper">
      <Helmet>
        ...
        <link rel="webmention" href="https://webmention.io/username/webmention" />
        <link rel="pingback" href="https://webmention.io/username/xmlrpc" />

      Helmet>
...
    div>
  )
}

When you start getting Webmentions from your target URLs, you should see them in your dashboard like this:

webmention.io dashboard

You can easily monitor your Webmentions in your dashboard.

How to Pull Webmentions Data to Your Website

This is the fun part where you'll pull your Webmentions data from the Webmention.io API. To do this, I created a Gatsby plugin called [gatsby-source-webmentions](https://www.npmjs.com/package/gatsby-source-webmentions)

NOTE: there's another plugin called [gatsby-plugin-webmentions](https://github.com/ChristopherBiscardi/gatsby-plugin-webmention) which pulls in Webmentions data from webmention.io API and makes them available in Graphql.

Spruce, if there's already a Gatsby plugin why create another one?

I created this plugin for two reasons:

First because I can, and why not.
Second, for image optimization – this plugin lets you use the gatsby-image plugin to optimize the images returned by the API.

How to Install the Plugin

To install the plugin, open your system terminal or the VS Code integrated terminal and run the following:

npm install gatsby-source-webmentions

Next you'll need to add the plugin to your gatsby-config.js plugins array:

   { 
      resolve: "gatsby-source-webmentions",
      options: {
        DOMAIN: "example.com", // without https and any slashes
        TOKEN: process.env.WEBMENTIONS_TOKEN, // token from webmention.io
        perPage: 100, // optional
      },

The plugin takes a few options:

DOMAIN: the domain name you used to sign in to webmention.io
TOKEN: the token you got from your webmention.io dashboard
perPage: the number of Webmentions you want to fetch per page (this is completely optional)

To avoid pushing your secret token to GitHub add it as an environmental variable.

How to Display Webmentions on the Client Side

If you're dynamically creating your pages with the createPage Node API there's a high chance that you passed the slug variable to all your site pages. If you are unsure or you named it something else just check your site gatsby-node.js file.

Using Create pages to generate a slug for site pages

In your src/templates/blog.js or wherever your page templates are, you'll query Webmentions only if the wm_slug matches the page slug.

import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/Layout"
import Comment from "./Comment"


export const query = graphql`
  query($slug: String!) {
    allWebmention(filter: { wm_slug: { eq: $slug } }) {
        totalCount
        edges {
          node {
            id
            published
            publishedFormated: published(formatString: "MMM Do, YYYY")
            author {
                name
                photo
                url
            }
            url
            wm_id
            content {
              html
            }
          }
        }
      }
    }
`

export default function BlogPost({ data, location }) {
...
  const mentions = data.allWebmention

  return (
    <>
      <Layout>
      ...
      // display mentions in a react component
      Layout>
    
  )
}

wm_slug is a node I created to grab the slug from the wm_target.

Now you can map over all the Webmentions for that target slug and display them in a React Component:

import React from "react"
import { graphql } from "gatsby"
import Layout from "../components/Layout"
import Comment from "./Comment"


export const query = graphql`
  query($slug: String!) {
    allWebmention(filter: { wm_slug: { eq: $slug } }) {
    // graphql queries
      }
    }
`

export default function BlogPost({ data }) {
...
  const mentions = data.allWebmention

  return (
    <>
      <Layout>
      ...
          <ol className="webmentions__list">
      {mentions.edges.map(edge => (
        <Comment
          key={edge.node.wm_id}
          imageUrl={edge.node.author.photo}
          authorUrl={edge.node.author.url}
          authorName={edge.node.author.name}
          dtPublished={edge.node.published}
          dtPublishedFormated={edge.node.publishedFormated}
          content={edge.node.content && edge.node.content.html}
          url={edge.node.url}
        />
      ))}
      ol>
      Layout>
    
  )
}

How to Group the Webmentions by Type

Although this is completely optional, it is a good idea to group your Webmentions by type:

"in_reply_to" – for replies
"like_of" – for likes
"retweet_of" – for retweets, etc.

...

export const query = graphql`
  query($slug: String!) {
    allWebmention(filter: { wm_slug: { eq: $slug } }) {
      likes: group(field: like_of) {
        totalCount
        edges {
          node {
             // node queries
          }
        }
      }

      replies: group(field: in_reply_to) {
        totalCount
        edges {
          node {
            // node queries
        }
      }
    }
}
...

How to Optimize the Webmentions Author Images

I mentioned earlier that the gatsby-source-plugin allows us to optimize the images returned from the Webmentions query.

To be able to optimize the images you must have [gatsby-plugin-image](https://www.gatsbyjs.com/plugins/gatsby-plugin-image/), gatsby-plugin-sharp, gatsby-transformer-sharp and gatsby-source-filesystem installed:

export const query = graphql`
  query($slug: String!) {
    allWebmention(filter: { wm_slug: { eq: $slug } }) {
      likes: group(field: like_of) {
        totalCount
        edges {
          node {
            // other node queries
            author {
                photoSharp {
                  childImageSharp {
                    gatsbyImageData(
                      width: 38
                      placeholder: BLURRED
                      formats: [AUTO, WEBP, AVIF]
                )
              }
             }
            }
          }
        }
      }
    }
`

For other optimizations and image processing, refer to the gatsby-plugin-image reference guide.

How to Add Custom Pagination

You can paginate your Webmentions with one of the many Gatsby pagination plugins. But all I wanted was a simple "Load More" button, and thankfully smarter people like Eric Howey have already thought about this.

The code below is from the article Load more button and infinite scroll in Gatsby (although I made a few adjustments to it):

import React, { useState, useEffect } from "react"
import { graphql } from "gatsby"
import Button from "./Button"
import Comment from "./Comment"

export const query = graphql`
  query($slug: String!) {
    allWebmention(filter: { wm_slug: { eq: $slug } }) {
        totalCount
        edges {
          node {
          // node queries
         }
        }
       }
      }

export default function BlogPost({ data }) {
...
  const replies = data.allWebmention

  const [state, setState] = useState({
    list: [...replies.slice(0, 5)],
    Load_more: false,
    has_more: replies.length > 5,
  })
  const handleState = () => {
    state.Load_more = true
  }
  //handle loading more mentions
  useEffect(() => {
    if (state.Load_more && state.has_more) {
      const currentLength = state.list.length
      const is_more = currentLength < replies.length
      const new_list = is_more
        ? replies.slice(currentLength, currentLength + 5)
        : []
      setState.list = [...state.list, ...new_list]
      setState.Load_more = false
    }
  }, [state.Load_more, state.has_more, replies, state.list])

  useEffect(() => {
    const is_more = state.list.length < replies.length
    setState.has_more = is_more

  }, [state.list,replies.length])
  return (
    
      {replies.length > 0 ? (
        <>
    Comments {replies[0].totalCount} 
    
      {state.list.edges.map(edge => (
        
      ))}
      
      
      {state.has_more ? (
          
        
      ) : (
        No Webmentions found
      )}
    
  )
}

Continuous Deployment with Webmentions

As you might have noticed, your Webmentions data are pulled at build time. This means that users won't see new Webmentions unless your site has been built.

I host my site in Gatsby Cloud and to avoid crawling out of bed at midnight to build my site. It provides us with a WEBHOOK that can trigger a build for your site even while you are sleeping.

If you are using Gatsby cloud, go to your dashboard and copy the Webhook:

Webhooks from Gatsby Cloud dashboard

Once you have copied the Webhook, head over to your webmention.io dashboard, click on Web hooks, and paste the copied Webhook into the form:

webmention.io web hooks

That's it – you are done. Now any time you get a new Webmention the Web hook will build your site automatically.

Wrapping Up

In this tutorial we learned how to implement Webmentions on your Gatsby site. If you have any questions or you found this tutorial useful, please feel free to connect with me on Twitter @sprucekhalifa. Thank you.

Happy Coding!

What is Website Theming? How to Use CSS Custom Properties and Gatsby.js to Customize Your Site

Spruce Emmanuel — Thu, 01 Jul 2021 18:19:21 +0000

In this article, I'm going to show you how to theme your website so users can customize certain elements to their tastes.

We'll talk about website themes, how theming works, and we'll end with a demo so you can see it in action. Let's dive in.

What is a Website Theme?
What is theming?
Why Should You Care About Theming?
“It’s their screen, machine and software”
Theming increases readability
All the cool cats are using it - theming in the wild
How to Use Theme Properties
What are theme properties?
What are CSS custom properties?
How to set up theme properties in Gatsby.js
How to store the theme properties
How to transform theme properties to CSS custom properties
How to Use the Theme Switcher Component
The markup
How to set up the state
How to update the state
How to persist state to LocalStorage
Conclusion

Who is this article for?

This article is aimed at developers who already have a basic knowledge of CSS, React, and Gatsby who want to learn how to create a user theme-able Gatsby or React app.

By the end of this article, you should understand how theming works and how to implement theming on your Gatsby sites.

What is a theme?

In order to understand what website theming is, let's first look at what a website theme is and what make up a theme.

A theme in the context of a website is the overall look, feel, and style of your website. A theme may include:

fonts
font size
color schemes
layouts
aesthetics

A theme controls the design of your website. It determines what your website looks like from the surface, and it is the part of your website that has a direct impact on your users.

A theme is also a set of styles worn by a website.

What is Theming?

Theming is to a website what clothes are to our bodies. Imagine wearing the same clothes to a meeting, a wedding, and a farm - sounds funny right? Of course you probably wouldn't do that if you had the choice.

For each occasion you would wear the appropriate type or style of dress. That’s what website theming is – it allows our users to choose the look and feel of our website with a set of styles based on different occasions.

Theming is simply giving users the ability to make customizations to our websites and apps. You can also think about theming as a set of customizations users can make to our websites or applications based on their choices.

Theming happens when the user is able to tell your website what they prefer to see, for example:

Clicking a button to change the background of a website to red or black
Increasing or decreasing the font size of a site website/application
Clicking a button to remove content not relevant to the user.

Here’s a tip: letting or asking your users to determine your website theme from scratch is a bad idea. You or your team should provide users with an accessible and usable default theme, since in most cases many users will never customize “their view” on your website no matter how easy it is. |

Why should you care about website theming?

Apart from letting users know you care about their personal preferences, there are other reasons to let your users theme your website. Some of them include:

“It’s their Screen, Machine and Software”

This is a quote from Jakob Nielsen's 2002 article: Let users control font size.

The fact that your website is running on the user’s screen, machine, and software (and probably draining their batteries too) is enough reason them to be able to customize their experience on your site.

Theming improves website readability

Quoting D. Bnonn from the article: 16 Pixels Font Size: For Body Copy. Anything Less Is A Costly Mistake

Fact: Most Web Users Hate The “Normal” Font Size.

With this fact in mind, theming can help readers out by allowing them to choose the font size that suites their eyes best.

Oh and here is another quote from the same article.

Readership = Revenue.

All the cool cats are using it – theming in the wild

A lot of developers have used the idea of theming to create dark mode versions of their websites. Other’s have taken this idea further to allow users change font-size, colors, and background based on individual preferences.

Here's an example of this kind of customization in the Twitter web app:

Twitter customize theme UI

Still not feeling motivated yet? If you still need more proof that theming is a good idea, here’s a whole list of websites, apps, and software that use theming to provide dark and light modes for their users.

How to Use Theme Properties

Now that you know what theming is and have seen sites that use this idea of theming in their websites and applications, let’s learn what theme properties are.

What are theme properties?

Theme properties are a set of CSS custom properties that make up a theme. Remember that “a theme is a set of styles worn by a website” – so theme properties are all the properties that make up the styles a site wears. For example:

[data-theme="default"] {
  --font-size: 20px;
  --background: red;
}

In the example above, [data-theme="default"] is our theme, while all the CSS custom properties inside are the theme properties. You get the idea, right?

Here’s a tip: your theme properties don’t have to be just CSS custom properties. They can also be any valid CSS properties that you want to apply to a specific theme.

Before we move forward, let’s first understand what CSS custom properties are

What are CSS Custom Properties (also known as CSS variables)?

CSS custom properties are entities which hold values that you can reuse throughout an entire site or document.

For the sake of this tutorial we are not going to cover CSS custom properties in depth. You can read more about custom properties here.

Also there are a lot of great tutorials out there that cover CSS custom properties and how to use them for theming, so we’ll leave the theory to those other articles.

For a strategic guide on how to use CSS custom properties for theming check out this awesome article: A Strategy Guide To CSS Custom Properties.

Although we are not covering CSS custom properties in depth, I want to point out a few reasons why CSS custom properties are ideal for website theming:

They are reusable – you can use them throughout your CSS
They reduce the complexity of our code, since you no longer need to create different stylesheet to achieve a theme-able website
They are available at runtime, which means you can update their value in the browser, via JavaScript, with immediate results.

How to Set Up Theme Properties in Gatsby.js

Of course you can hard code theme properties directly inside your CSS file like any other CSS properties. But having to scroll up a few lines of your CSS code anytime you want to make a few changes to your themes sounds tedious, right?

Max Böck in his article “Color Theme Switcher” advises defining our themes in a central location.

Having a central location (file) where you can easily access and manage your themes sounds like an interesting idea. And this is the kind of thing Gatsby was made for.

Quoting the Gatsby docs:

“A core feature of Gatsby.js is it’s ability to load data from anywhere.”

This means you can source data from a JSON file which will be available at build time. When you import this data you can then iterate over it with the Array.map method and render it in a React component.

How to Store Theme Properties

In your Gatsby project folder, create a directory called content if it doesn't already exists. Then add a new file called themes.json with the following content:

[
  {
    "id": "default",
    "colors": {
      "primary-color": "#0250bb",
      "text": "#20123a",
      "text-alt": "#42425a",
      "border": "#ededf0",
      "background": "#ffffff",
      "background-alt": "#f9f9fa",
      "color-scheme": "light"
    }
  },
  {
    "id": "dark",
    "colors": {
      "primary-color": "#7f5af0",
      "text": "#fffffe",
      "text-alt": "#94a1b2",
      "border": "#010101",
      "background": "#16161a",
      "background-alt": "#242629",
      "color-scheme": "dark"
    }
  },
  {
    "id": "warm",
    "colors": {
      "primary-color": "#ff8e3c",
      "text": "#0d0d0d",
      "text-alt": "#2a2a2a",
      "background": "#eff0f3",
      "background-alt": "#fff",
      "border": "rgba(0,0,0,.1)",
      "color-scheme": "light"
    }
  },
// Add other themes here
]

Each theme gets an id, a set of theme properties, and a CSS color-scheme property.

Here’s a tip – we use the CSS color-scheme property to tell which color scheme (light/dark) our webpage should be rendered in. For a better understanding of color-scheme please refer to this color scheme guide.

How to Transform Theme Properties to CSS Custom Properties

Right now, the color themes stored in our content/themes.json files are just raw data. They need to be transformed into CSS custom properties before they can actually do anything meaningful.

Data is a collection of facts, such as numbers, words, measurements, observations or just descriptions of things.

We are going to need our CSS custom properties to be dynamically generated and added as an inline