DEV Community: Lennart

Smooth Shadows for Images using their Dominant Color

Lennart — Fri, 06 Aug 2021 14:15:31 +0000

If you've seen posts about Neumorphism or CSS generators like neumorphism.io you're probably familiar with these super smooth shadows the elements have. While designing a whole page in this style would be a bit too much for me personally I do like the shadows! In fact, at some point the design blog Abduzeedo had smooth shadows on their images (using the dominant color) -- so exactly what I'll show today.

You can see a preview of the effect on my Emilia Theme site. The end result will also be the same as this Codesandbox you can look at and fork.

Prerequisites

While not necessary for this technique to work I'm using Gatsby and gatsby-plugin-image to handle and display the images. I'm doing this because gatsby-plugin-image and its gatsbyImageData supports the placeholder value DOMINANT_COLOR and gives back this value as backgroundColor -- so you can directly query the dominant color of an image.

Set up a new site and install the necessary plugins for gatsby-plugin-image following its instructions, e.g. with npm init gatsby and the Add responsive images option at the end.

You can use Color Thief to process your images and get back information like the dominant color in any JS framework. For React there's also color-thief-react (although I haven't tried that personally). The library polished will also work in any JS framework.

Query your images and make sure that you have the DOMINANT_COLOR option for the placeholder for gatsbyImageData. An example page could be:

import React from "react"
import { graphql } from "gatsby"
import { GatsbyImage, getImage } from "gatsby-plugin-image"

export default function Home({ data }) {
  return (
    <main>
      <h1>Images with Dominant Color Smooth Shadows</h1>
      <div>
        {data.images.nodes.map((image) => (
          <GatsbyImage alt="" image={getImage(image)} />
        ))}
      </div>
    </main>
  )
}

export const query = graphql`
  {
    images: allImageSharp {
      nodes {
        gatsbyImageData(quality: 90, width: 800, placeholder: DOMINANT_COLOR)
      }
    }
  }
`

image.gatsbyImageData.backgroundColor inside the .map() will give back the dominant color.

Creating the function to generate shadows

Create a new function called generateShadow with the single argument color in your page. As the function will use a method from another library you'll first need install polished.

npm install polished

polished is "a lightweight toolset for writing styles in JavaScript" and features handy helper functions, including rgba which you'll use to create a RGBA color string inside the generateShadow function.

The generateShadow function will take a color and iterate over the arrays shadowX, shadowY, and transparency internally to create an array of valid box-shadow strings. It returns a string that you can use with box-shadow in CSS since you can chain them with a comma.

// Rest of imports
import { rgba } from "polished"

function generateShadow(color) {
  const shadowX = []
  const shadowY = []
  const transparency = []

  let shadowMap = []

  for (let i = 0; i < 6; i++) {
    const c = rgba(color, transparency[i])

    shadowMap.push(`0 ${shadowX[i]} ${shadowY[i]} ${c}`)
  }

  return shadowMap.join(", ")
}

// Rest of page

But how does one get the correct values for the three arrays? @brumm created the awesome website Smooth Shadow which you can use to get these values. For my purposes I used 6 layers and only changed the final transparency to 0.15.

So you'll get the CSS:

box-shadow: 0 2.8px 2.2px rgba(0, 0, 0, 0.042), 0 6.7px 5.3px rgba(0, 0, 0, 0.061),
  0 12.5px 10px rgba(0, 0, 0, 0.075), 0 22.3px 17.9px rgba(0, 0, 0, 0.089),
  0 41.8px 33.4px rgba(0, 0, 0, 0.108), 0 100px 80px rgba(0, 0, 0, 0.15);

But that's a black shadow 😬 Time to make a colorful one. You can translate the generated values into their respective arrays.

As always, MDN as a good explanation on box-shadow. The generated CSS from "Smooth Shadow" is in this syntax:

/* offset-x | offset-y | blur-radius | spread-radius | color */
box-shadow: 0 2px 2px 1px rgba(0, 0, 0, 0.2);

So offset-x goes into shadowX, offset-y into shadowY, and the last value of rgba into transparency.

Depending on your values your generateShadow function now should look something like this:

// Rest of imports
import { rgba } from "polished"

function generateShadow(color) {
  const shadowX = ["2.8px", "6.7px", "12.5px", "22.3px", "41.8px", "100px"]
  const shadowY = ["2.2px", "5.3px", "10px", "17.9px", "33.4px", "80px"]
  const transparency = [0.042, 0.061, 0.075, 0.089, 0.108, 0.15]

  let shadowMap = []

  for (let i = 0; i < 6; i++) {
    const c = rgba(color, transparency[i])

    shadowMap.push(`0 ${shadowX[i]} ${shadowY[i]} ${c}`)
  }

  return shadowMap.join(", ")
}

// Rest of page

Apply shadows to images

Now it's time to use generateShadow. Your complete page now should look something like this:

import React from "react"
import { graphql } from "gatsby"
import { GatsbyImage, getImage } from "gatsby-plugin-image"
import { rgba } from "polished"

function generateShadow(color) {
  const shadowX = ["2.8px", "6.7px", "12.5px", "22.3px", "41.8px", "100px"]
  const shadowY = ["2.2px", "5.3px", "10px", "17.9px", "33.4px", "80px"]
  const transparency = [0.042, 0.061, 0.075, 0.089, 0.108, 0.15]

  let shadowMap = []

  for (let i = 0; i < 6; i++) {
    const c = rgba(color, transparency[i])

    shadowMap.push(`0 ${shadowX[i]} ${shadowY[i]} ${c}`)
  }

  return shadowMap.join(", ")
}

export default function Home({ data }) {
  return (
    <main>
      <h1>Images with Dominant Color Smooth Shadows</h1>
      <div>
        {data.images.nodes.map((image) => (
          <GatsbyImage alt="" image={getImage(image)} />
        ))}
      </div>
    </main>
  )
}

export const query = graphql`
  {
    images: allImageSharp {
      nodes {
        gatsbyImageData(quality: 90, width: 800, placeholder: DOMINANT_COLOR)
      }
    }
  }
`

The last step is to use the style prop from gatsby-plugin-image to apply the box-shadow to the outer wrapper of <GatsbyImage />.

{
  data.images.nodes.map((image) => (
    <GatsbyImage
      alt=""
      image={getImage(image)}
      style={{
        boxShadow: generateShadow(image.gatsbyImageData.backgroundColor),
      }}
    />
  ))
}

Bonus 🍬

If you want to practise some skills you have and/or go beyond this little guide, here are some ideas:

Change generateShadow to take in the generated shadow from Smooth Shadow and replace the rgb with the color param
Use the developer tools inside your browser, go to the "Sources" tab and browse the source code of Smooth Shadow to reverse engineer the functions so that generateShadow can take the same params as the webpage

Generating QR Codes from any String in Gatsby

Lennart — Fri, 06 Aug 2021 14:12:21 +0000

One of the many side-effects of the coronavirus pandemic is that the QR code got some attenion (again). When it first came out you saw it everywhere but the last couple of years it slowly vanished again -- until now where your vaccination certificate or check-in apps all use QR codes again.

Generating QR codes from any string you wish in Gatsby could be done in multiple ways. Normally for such operations you'd set up a transformer plugin but realistically you wouldn't want every string to be converted to a QR code. Thus you can use the createSchemaCustomization API to individually add a new field to your desired node and transform a specific sibling field. This saves work & build time! You can take this YAML schema as an example:

- name: Author's Homepage
  description: Visit the author's homepage for more information and other cool stuff
  link: https://www.lekoarts.de

Gatsby will generate a InformationYaml type out of it and you want to have an additional field called qrCodeDataURL that contains the data URI of a QR code generated from the link field. Then you can query it like this:

query {
  informationYaml {
    name
    link
    description
    qrCodeDataURL
  }
}

Continue reading to learn how to do this! You can find the finished code on Codesandbox and you can also check out Filter Future Posts on a Gatsby Blog to see the API in a similar example.

Setup

I'm assuming that you already have a Gatsby project set up with some specific fields you want to convert. If not, you can run npm init gatsby and choose the markdown option. Then you can use the frontmatter to add an additional field. Stop your development server if it's still running.

My example is using a YAML file that is represented as InformationYaml in the GraphQL schema of Gatsby. You've seen the shape of it in the intro of this post.

Install two dependencies you'll need:

npm install lodash.get qrcode

Generating QR codes

Open your gatsby-node.js file and add the installed package, and the boilerplate to use Gatsby's schema customization API:

const get = require("lodash.get")
const QRCode = require("qrcode")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions
}

With the function createTypes you'll explicitly define the GraphQL types (in this case in GraphQL SDL syntax), with createFieldExtension you'll create a so called directive/extension that you then can reuse throughout your types.

Adding the new field to the type

Since the QR code should be available at the field qrCodeDataURL it needs to be added to the desired GraphQL type.

const get = require("lodash.get")
const QRCode = require("qrcode")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  createTypes(`
    type InformationYaml implements Node {
      qrCodeDataURL: String
    }
  `)
}

But if you'd query this field now you'd only get null as a result. The data needs to be generated first before querying it.

Creating the field extension

Use the createFieldExtension action to create a custom directive that you can use on the newly created qrCodeDataURL field:

const get = require("lodash.get")
const QRCode = require("qrcode")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  createFieldExtension({
    name: "createQRCode",
    args: {
      fieldName: "String!",
    },
    extend({ fieldName }) {
      return {
        resolve: createQRCode(fieldName),
      }
    },
  })

  createTypes(`
    type InformationYaml implements Node {
      qrCodeDataURL: String @createQRCode(fieldName: "link")
    }
  `)
}

But the last piece to this puzzle is missing: The createQRCode function. The field extension will use result of it as the value of the qrCodeDataURL field. createQRCode gets passed all the fieldName you use (in this example "link").

const get = require("lodash.get")
const QRCode = require("qrcode")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  const createQRCode = (fieldName) => async (source) => {
    const string = get(source, fieldName)
    let qrCode = ``

    try {
      qrCode = await QRCode.toDataURL(string, { scale: 6 })
    } catch (err) {
      console.error(err)
    }

    return qrCode
  }

  createFieldExtension({
    name: "createQRCode",
    args: {
      fieldName: "String!",
    },
    extend({ fieldName }) {
      return {
        resolve: createQRCode(fieldName),
      }
    },
  })

  createTypes(`
    type InformationYaml implements Node {
      qrCodeDataURL: String @createQRCode(fieldName: "link")
    }
  `)
}

You can find more information about qrcode's options on its GitHub page.

Using the result

Now you're able to query the new data! Start the development server and visit GraphiQL at localhost:8000/___graphql. If you explore the schema you should see qrCodeDataURL now. You can use this data URI as an image now, for example:

import * as React from "react"
import { graphql } from "gatsby"

export default function Home({ data }) {
  return (
    <main>
      <h1>{data.info.name}</h1>
      <p>
        {data.info.description}: <br />{" "}
        <a href={data.info.link}>Visit the website</a> or scan this QR code:
      </p>
      <img
        alt="QR Code to the authors homepage"
        src={data.info.qrCodeDataURL}
      />
    </main>
  )
}

export const query = graphql`
  {
    info: informationYaml {
      name
      link
      description
      qrCodeDataURL
    }
  }
`

Python: Comprehensions

Lennart — Fri, 06 Aug 2021 14:09:27 +0000

Comprehensions (and list comprehensions in particular) are probably the feature I love the most coming from JavaScript to Python. It enables you to write concise code for something you do very often: Iterating over a list, modifying the data a bit ("data massaging") and returning a list with the new entries.

One thing to note: List comprehension load the entire output into memory so this should only be used for small to medium-sized lists. In cases of big lists, use generators instead.

Basic Syntax (for lists):

[expression for item in iterable if conditional]

If you want to try the instructions below you can fire up the Python REPL. If you have Python installed run python in your terminal. Any Python code that starts with >>> symbols indicated that it was typed into a REPL.
To try out the JavaScript snippets you could use Quokka.js in your editor.

Examples

Iterating over the array and giving out the length of the word itself into a new list:

const names = ["James", "Naomi", "Amos", "Alex", "Bobbie", "Clarissa"]
const len_names = names.map((name) => name.length)
console.log(len_names)
// [ 5, 5, 4, 4, 6, 8 ]

>>> names = ["James", "Naomi", "Amos", "Alex", "Bobbie", "Clarissa"]
>>> len_names = [len(name) for name in names]
>>> print(len_names)
[5, 5, 4, 4, 6, 8]

Skipping the first item & last item (by index) and creating a list of dictionaries:

const names = ["James", "Naomi", "Amos", "Alex", "Bobbie", "Clarissa"]
const names_list = names
  .filter((_, id) => id !== 0 && id !== names.length - 1)
  .map((name) => ({ name, length: name.length }))
console.log(names_list)
// [ { name: 'Naomi', length: 5 }, { name: 'Amos', length: 4 }, { name: 'Alex', length: 4 }, { name: 'Bobbie', length: 6 } ]

>>> names = ["James", "Naomi", "Amos", "Alex", "Bobbie", "Clarissa"]
>>> names_list = [{ "name": name, "length": len(name) } for idx, name in enumerate(names) if idx != 0 and idx != len(names)-1]
>>> print(names_list)
[{'name': 'Naomi', 'length': 5}, {'name': 'Amos', 'length': 4}, {'name': 'Alex', 'length': 4}, {'name': 'Bobbie', 'length': 6}]

Tuple unpacking:

const students = [
  ["James", 16],
  ["Naomi", 20],
]
const nameWithAge = students.map((s) => [s[0].length + s[1], ...s])
console.log(nameWithAge)
// [ [ 21, 'James', 16 ], [ 25, 'Naomi', 20 ] ]

>>> students = [("James", 16), ("Naomi", 20)]
>>> nameWithAge = [[len(s[0])+s[1], *s] for s in students]
>>> print(nameWithAge)
[[21, 'James', 16], [25, 'Naomi', 20]]

Creating a list of characters from a string:

const myName = "LekoArts"
const arr = [...myName]
console.log(arr)
// [ 'L', 'e', 'k', 'o', 'A', 'r', 't', 's' ]

>>> my_name = 'LekoArts'
>>> arr = [l for l in my_name]
>>> print(arr)
['L', 'e', 'k', 'o', 'A', 'r', 't', 's']

Reversing strings in a tuple and returning them as a list:

const words = ["kayak", "LekoArts", "radar", "python"]
const reversed = words.map((word) => word.split("").reverse().join(""))
console.log(reversed)
// [ 'kayak', 'strAokeL', 'radar', 'nohtyp' ]

>>> words = ("kayak", "LekoArts", "radar", "python")
>>> reversed = [word[::-1] for word in words]
>>> print(reversed)
['kayak', 'strAokeL', 'radar', 'nohtyp']

You can also nest comprehensions. Here's a 3 by 3 identity matrix:

>>> matrix = [[1 if item_idx == row_idx else 0 for item_idx in range(0, 3)] for row_idx in range(0, 3)]
>>> print(matrix)
[[1, 0, 0], [0, 1, 0], [0, 0, 1]]

Python: Data Types

Lennart — Fri, 06 Aug 2021 14:06:01 +0000

Coming from JavaScript it's refreshing to learn Python as it has a big standard library and easy to pick up (especially if you have prior programming knowledge). Starting off with the data types I want to highlight some awesome features that Python has and interesting differences I saw. So don't expect this to be a complete guide or comparison of both.

Helper Functions

Python itself has helpful functions to help you define and discover the types. They are type(), dir(), and help().

>>> name = "Lennart"
>>> type(name)
<class 'str'>
>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'removeprefix', 'removesuffix', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']
>>> help(str.title)
Help on method_descriptor:

title(self, /)
    Return a version of the string where each word is titlecased.

    More specifically, words start with uppercased characters and all remaining
    cased characters have lower case.

Numbers

Python has more explicit types for working with numbers. In JavaScript they are mashed together into Number.

>>> x = 4
>>> y = 5.0
>>> z = 42j
>>> type(x)
<class 'int'>
>>> type(y)
<class 'float'>
>>> type(z)
<class 'complex'>

Tuple

Tuples are immutable collections that you can use to track related but different items. Thus they are great as immutable keys in set and dict. Unpacking is a way of quickly getting information from a tuple:

>>> favourite_food = ("Italian", "Pizza")
>>> cuisine, name = favourite_food
>>> cuisine
'Italian'
>>> name
'Pizza'

Set

A set is mutable and stores immutable types in an unsorted way. You can't store other mutable types (like list, set or dict) in it. A set can only contain unique items.

This is great to quickly deduplicate a list:

>>> names = ["Luke", "Leia", "Malak", "Luke"]
>>> set(names)
{'Leia', 'Luke', 'Malak'}

You can execute a couple of mutations on a set (.add or .discard etc.) but I definitely found .update interesting since you can add multiple values at once:

>>> chars = {"James", "Naomi", "Amos"}
>>> addition = {"Alex", "Julie"}
>>> chars.update(addition)
>>> chars
{'Julie', 'James', 'Naomi', 'Alex', 'Amos'}

Another cool thing are the set operations -- union and intersection:

>>> chars = {"James", "Naomi", "Amos"}
>>> favourite_chars = {"James"}
>>> chars | addition
{'Julie', 'James', 'Naomi', 'Alex', 'Amos'}
>>> chars & favourite_chars
{'James'}

Dictionary

A dictionary is mutable and stores key:value pairs (keys can only be immutable types). Thus it's extremely fast to search in. Besides the standard stuff there are three helpful methods: keys(), values(), items():

>>> chars = { "expanse": "Holden", "star_wars": "Luke" }
>>> chars.keys()
dict_keys(['expanse', 'star_wars'])
>>> chars.values()
dict_values(['Holden', 'Luke'])
>>> chars.items()
dict_items([('expanse', 'Holden'), ('star_wars', 'Luke')])

While these functions alone are not doing much, they can come in really handy in for-loops:

>>> for franchise, char in chars.items():
...     print(f"The char {char} exists in the franchise {franchise}")
...
The char Holden exists in the franchise expanse
The char Luke exists in the franchise star_wars

Since items() returns a list of tuples one can use tuple unpacking to get both values.

Adding a Draft Feature to Gatsby

Lennart — Fri, 06 Aug 2021 14:03:36 +0000

There are a lot of guides on the internet on how to add default values to your Gatsby schema, e.g. a draft entry in the frontmatter to hide posts that are still work-in-progress. However, all these solutions are kinda hacky, as they for example require you to use environment variables or even define the draft entry in every single frontmatter you have. Since Gatsby implemented its schema customization API there is an easy solution (and not hacky at all!) available. Most importantly: This quick tip is applicable to all data sources you have, not only markdown (and its frontmatter).

You can have a look at the codesandbox gatsby-draft-default-values to see the working code in a minimal example.

If you want to follow the example along, you can install the default blog starter by running gatsby new my-blog https://github.com/gatsbyjs/gatsby-starter-blog with gatsby-cli.

Setup

The default blog starter uses markdown for its content and you can use the so called frontmatter in markdown files to define additional data, such as e.g. a draft status (true or false). The goal is to define a default value for this draft status so that you don't have to define it in every markdown file but only in the ones you'd like to be a draft.

Add this to the existing gatsby-node.js file:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  createFieldExtension({
    name: "defaultFalse",
    extend() {
      return {
        resolve(source, args, context, info) {
          if (source[info.fieldName] == null) {
            return false
          }
          return source[info.fieldName]
        },
      }
    },
  })

  createTypes(`
    type MarkdownRemark implements Node {
      frontmatter: Frontmatter
    }
    type Frontmatter {
      draft: Boolean @defaultFalse
    }
  `)
}

In the createTypes function you have to define a nested type on the MarkdownRemark type (read Nested types for more info) to be able to type the draft field. On the draft field itself the custom extension is used as a directive. The directive allows you to reuse this action on other fields, too. In case you're using a CMS or other datasource than markdown you'll need to find and define your type (instead of MarkdownRemark) to have this working. I'd recommend using GraphiQL (localhost:8000/___graphql) if you're unsure about the names!

To be able to use the @defaultFalse directive, you need to define a custom extension with createFieldExtension. The source contains all fields from the frontmatter (in this case: title, description, date, and draft). info.fieldName is the name of the field you're applying the directive to – in this case draft. Fields that are not provided are null by default but because draft should be a boolean you need to return false in this case. If it's provided simply return the value.

Read the complete guide on Creating type definitions to get in-depth knowledge of how and why it works this way.

Usage

Now that the draft field is set up and defaults to false, you can go ahead and add a draft: true to the frontmatter of a blogpost.

---
title: "My Second Post!"
date: "2015-05-06T23:46:37.121Z"
draft: true
---

When opening GraphiQL you also should be able to query the draft field now and filter by it. A query to list all markdown posts that are not a draft looks like:

query {
  allMarkdownRemark(filter: { frontmatter: { draft: { eq: false } } }) {
    nodes {
      frontmatter {
        title
        description
        date
        draft
      }
    }
  }
}

Adding Support for Multiple Authors in Gatsby

Lennart — Fri, 06 Aug 2021 14:00:52 +0000

This quick tip will explain how you can have multiple authors for your blog posts. It's not limited to Markdown but the example Gatsby site will use that. You can apply the general technique also to your site that is powered by a CMS or other data source. See the example project on Codesandbox.

Please note that this article won't walk you through an example from start to finish but rather explain the concepts behind it. Feel free to clone gatsby-starter-blog and try it yourself after reading this blog post.

Setup

So, what's the starting point? For this example you'll start of with a markdown powered Gatsby site and each blog post has a frontmatter with things like title, slug, and author. Now you want to add the ability to add multiple authors to one blog post and also provide some additional information about the authors.

So the frontmatter of each blog post could look like:

---
title: "Second blog post"
date: 2020-01-02
slug: "/second-blog-post"
authors:
  - "Hermione"
  - "Ron"
---

For the detailed information (description, image) of each author you can use something like an authors.yml file. YAML files are a great fit for that usecase (e.g. allow comments, easy to parse and lint). Put the file together with some images into the same folder, set up gatsby-source-filesystem and gatsby-transformer-yaml and paste something in like:

- name: "Harry"
  description: "The chosen one"
  image: "./harry.jpg"
- name: "Ron"
  description: "Harry's best friend"
  image: "./ron.jpg"
- name: "Hermione"
  description: "Smartest girl"
  image: "./hermione.jpg"

The important bit here is that the name is unique and the frontmatter only references available names.

Creating the link

Now it's time for Gatsby's schema customization API to shine. The end goal is that you can query something like this:

{
  query {
    markdownRemark {
      frontmatter {
        title
        authors {
          description
          name
        }
      }
    }
  }
}

For this to work you'll need to create a foreign-key relationship between the blog posts and the authors. Or in other words: Between MarkdownRemark and AuthorsYaml. Because those are the respective types - you can see them by going to your GraphiQL instance at localhost:8000/___graphql.

Add to your gatsby-node.js file:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type MarkdownRemark implements Node {
      frontmatter: Frontmatter
    }

    type Frontmatter {
      authors: [AuthorsYaml] @link(by: "name")
    }
  `
  createTypes(typeDefs)
}

In order to explicitly define the nested frontmatter you first need define root type MarkdownRemark that then has the custom type Frontmatter. The part implements Node means that the type will use the Node interface that defines set of fields common to node objects created by source plugins/transformers.

The important bit here is:

authors: [AuthorsYaml] @link(by: "name")

AuthorsYaml is the type for your yaml file, the bracket notation means that authors is having an array of items with the type of AuthorsYaml. Now you're saying that both should be linked by name. Remember: The name is common in both files and unique.

Learn more about it in-depth here: Gatsby's docs about schema customization.

Other data sources

This quick tip explained the concept with markdown files and a yaml file. But what about CMSs or other local files? You'll want to get the type names (e.g. from GraphiQL) and also type until you reached the nested type. Use a unique property for linking.

Filter Future Posts on a Gatsby Blog

Lennart — Fri, 06 Aug 2021 13:59:01 +0000

You can leverage Gatsby's GraphQL data layer to filter blog posts that are in the future. This TODAY variable allows you to e.g. build your site once a day and automatically have it published. A use case would be a podcast website where the author recorded the episode and already has written the description in advance. This way you also don't have to worry about remembering setting a "draft" variable or to be able to push changes up when you want something published.

If you need a TL;DR: You can visit the final example on Codesandbox (have a look at gatsby-node.js and the filtering in src/pages/index.js).

Setup

Install gatsby-starter-blog with Gatsby's CLI:

gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

When starting the development server you'll see an overview of all posts on the index page. The end goal is to filter out all future posts from this list.

First, you should change the date on one post inside content/blog to a future date. In the linked Codesandbox the post new-beginnings was changed. You will still see all posts in the overview.

Stop the development server and install a function from Lodash that you'll use in the next step:

npm install lodash.get

Creating the extension

Open your gatsby-node.js file and add the installed package, and the boilerplate to use Gatsby's schema customization API:

const get = require("lodash.get")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions
}

Since gatsby-starter-blog is powered by Markdown you'll want to add your isFuture field to the markdown type. It's called MarkdownRemark — you are probably used to querying that in GraphQL queries. Going to GraphiQL (localhost:8000/___graphql) and Docs (top right corner) => Query also reveals all available types.

Adding this type definition defines the mentioned field at the root of the Markdown type:

const get = require("lodash.get")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  createTypes(`
    type MarkdownRemark implements Node {
      isFuture: Boolean!
    }
  `)
}

The notation Boolean! means that the field is of type Boolean and is Non-Nullable.

Creating the helper function

In the next step you'll create the helper function that returns either true or false depending on whether the input date is in the future or not.

const get = require("lodash.get")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  const isFuture = (fieldName) => (source) => {
    const date = get(source, fieldName)
    return new Date(date) > new Date()
  }

  createTypes(`
    type MarkdownRemark implements Node {
      isFuture: Boolean!
    }
  `)
}

The concept used there is called Currying. For this example it means:

If you run isFuture("myName") you'll receive a function:

;(source) => {
  const date = get(source, "myName")
  return new Date(date) > new Date()
}

So what is that function doing? With the lodash.get function you're able to input a string with only one word (e.g. myName) or a word with dot notation (e.g. myName.field). The latter is used to access information in objects. The lodash.get function translates the string and enables you to access that information. If you later console.log(source) you'll see that you have access to source.frontmatter and other fields. It then checks the date with the current date and returns true if it's in the future, otherwise false.

Next, use createFieldExtension and the just created isFuture function:

const get = require("lodash.get")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  const isFuture = (fieldName) => (source) => {
    const date = get(source, fieldName)
    return new Date(date) > new Date()
  }

  createFieldExtension({
    name: "isFuture",
    args: {
      fieldName: "String!",
    },
    extend({ fieldName }) {
      return {
        resolve: isFuture(fieldName),
      }
    },
  })

  createTypes(`
    type MarkdownRemark implements Node {
      isFuture: Boolean!
    }
  `)
}

createFieldExtension accepts three arguments. name will be name of the directive, args the information you can give it and extend is a function that has to return a (partial) field config. In more verbose terms (including isFuture) you could write it like this:

const isFuture = (fieldName, source) => {
  const date = get(source, fieldName)
  return new Date(date) > new Date()
}

createFieldExtension({
  name: "isFuture",
  args: {
    fieldName: "String!",
  },
  extend(options) {
    return {
      resolve(source) {
        return isFuture(options.fieldName, source)
      },
    }
  },
})

So the the code you'll be using is destructuring the options and passing source via Currying to isFuture.

After adding the field extension to the field, the final code should look like:

const get = require("lodash.get")

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes, createFieldExtension } = actions

  const isFuture = (fieldName) => (source) => {
    const date = get(source, fieldName)
    return new Date(date) > new Date()
  }

  createFieldExtension({
    name: "isFuture",
    args: {
      fieldName: "String!",
    },
    extend({ fieldName }) {
      return {
        resolve: isFuture(fieldName),
      }
    },
  })

  createTypes(`
    type MarkdownRemark implements Node {
      isFuture: Boolean! @isFuture(fieldName: "frontmatter.date")
    }
  `)
}

As the date is defined in the frontmatter the fieldName is frontmatter.date. If you would place the isFuture field in the frontmatter itself you would use only date for the fieldName.

Start the development server, head to GraphiQL and see that you now can query isFuture on MarkdownRemark nodes!

You now can filter allMarkdownRemark with filter: { isFuture: { eq: false } } to hide posts. See an example on Codesandbox.

Where to go from here

Congrats, you just created a generic field extension that allows you to generate a isFuture field! You can not only use that with Markdown files but with any type in the GraphQL schema.

Lookup the type you want to modify in GraphiQL and add the isFuture field where appropriate. If you're unsure what value you have to pass into fieldName, you can inspect the passed source and see what's available.

Adding Line Numbers and Code Highlighting to MDX

Lennart — Fri, 06 Aug 2021 13:55:28 +0000

In this very short quick tip you'll learn how to set up code blocks in MDX and Gatsby that support line numbers and code highlighting using the code renderer prism-react-renderer. A preview can be found on CodeSandbox.

First, make sure that you have a MDX blog set up. If you have that already, you can skip to the packages. If not, you should first read Getting Started with MDX on Gatsby's documentation.

Install the necessary packages for this quick tip:

npm install mdx-utils prism-react-renderer

Create a Code React component in src/components/code.js and leave the file empty for now.

Also create a CSS file:

html,
body {
  margin: 0;
  padding: 0;
}

html {
  font-family: sans-serif;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
}

.prism-code {
  font-size: 1rem;
  padding-top: 1rem;
  padding-bottom: 1rem;
  -webkit-overflow-scrolling: touch;
  background-color: transparent;
  overflow: initial;
}

.token {
  display: inline-block;
}

p > code,
li > code {
  background: rgb(1, 22, 39);
  color: rgb(214, 222, 235);
  padding: 0.4em 0.3rem;
}

.gatsby-highlight {
  font-size: 1rem;
  position: relative;
  -webkit-overflow-scrolling: touch;
  overflow: auto;
}

gatsby-highlight > code[class*="language-"],
.gatsby-highlight > pre[class*="language-"] {
  word-spacing: normal;
  word-break: normal;
  overflow-wrap: normal;
  line-height: 1.5;
  tab-size: 4;
  hyphens: none;
}

.line-number-style {
  display: inline-block;
  padding-left: 1em;
  padding-right: 1em;
  width: 1.2em;
  user-select: none;
  opacity: 0.3;
  text-align: center;
  position: relative;
}

.highlight-line {
  background-color: rgb(2, 55, 81);
  border-left: 4px solid rgb(2, 155, 206);
}

.highlight-line .line-number-style {
  opacity: 0.5;
  width: calc(1.2em - 4px);
  left: -2px;
}

Switch to your file that contains the MDXProvider. If you use e.g. the defaultLayouts option inside gatsby-plugin-mdx of gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-mdx",
      options: {
        defaultLayouts: {
          default: require.resolve("./src/components/layout.js"),
        },
      },
    },
  ],
}

You'll need to add the MDXProvider and the rest of the following code (it's essentially the components placed into the wrapping MDXProvider) to your Layout file:

import * as React from "react"
import { MDXProvider } from "@mdx-js/react"
import { preToCodeBlock } from "mdx-utils"
import Code from "./code"
import "./layout.css"

const components = {
  pre: (preProps) => {
    const props = preToCodeBlock(preProps)
    if (props) {
      return <Code {...props} />
    } else {
      return <pre {...preProps} />
    }
  },
}

const Layout = ({ children }) => (
  <MDXProvider components={components}>
    <div style={{ margin: "0 auto", maxWidth: 960, padding: "2rem" }}>
      {children}
    </div>
  </MDXProvider>
)

export default Layout

The important bit is that you pass components into the provider and the previously created Code React component is used.

Add the following to said component:

import * as React from "react"
import Highlight, { defaultProps } from "prism-react-renderer"
import theme from "prism-react-renderer/themes/nightOwl"

const RE = /{([\d,-]+)}/

const calculateLinesToHighlight = (meta) => {
  if (!RE.test(meta)) {
    return () => false
  }
  const lineNumbers = RE.exec(meta)[1]
    .split(`,`)
    .map((v) => v.split(`-`).map((x) => parseInt(x, 10)))
  return (index) => {
    const lineNumber = index + 1
    const inRange = lineNumbers.some(([start, end]) =>
      end ? lineNumber >= start && lineNumber <= end : lineNumber === start
    )
    return inRange
  }
}

const Code = ({ codeString, language, metastring, ...props }) => {
  const shouldHighlightLine = calculateLinesToHighlight(metastring)

  return (
    <Highlight
      {...defaultProps}
      code={codeString}
      language={language}
      theme={theme}
      {...props}
    >
      {({ className, style, tokens, getLineProps, getTokenProps }) => (
        <div className="gatsby-highlight" data-language={language}>
          <pre className={className} style={style}>
            {tokens.map((line, i) => {
              const lineProps = getLineProps({ line, key: i })

              if (shouldHighlightLine(i)) {
                lineProps.className = `${lineProps.className} highlight-line`
              }

              return (
                <div {...lineProps}>
                  <span className="line-number-style">{i + 1}</span>
                  {line.map((token, key) => (
                    <span {...getTokenProps({ token, key })} />
                  ))}
                </div>
              )
            })}
          </pre>
        </div>
      )}
    </Highlight>
  )
}

export default Code

The calculateLinesToHighlight helper function gets the metastring as an input which is the notation for the line highlighting. As you can see in the linked CodeSandbox example you can write {1,9-12} to highlight the first and 9th to 12th line.

Language Tabs for Markdown & MDX Code Blocks

Lennart — Fri, 06 Aug 2021 13:51:05 +0000

Integrating syntax highlighting in Gatsby is solvable with solutions like gatsby-remark-prismjs or prism-react-renderer. When creating the code block in Markdown you specify the desired language (e.g. js or css) after the opening three backticks. It's a nice touch to display the specified language also in the code block itself, like I do it on my blog here:

const harry = spell("lumos")

The following two quick tips explain how to integrate this feature with gatsby-remark-prismjs or prism-react-renderer (Markdown or MDX respectively).

Markdown & gatsby-remark-prismjs

I created the codesandbox language-tabs-for-gatsby-remark-prismjs which you can have a look at the final and working code if you prefer to jump straight to the solution.

Set up a Gatsby project which allows you to source data from Markdown. You can e.g. run npm init gatsby and select the Markdown option. Now install gatsby-remark-prismjs and configure your gatsby-config.js & gatsby-browser.js accordingly. Add some dummy content to one of your markdown files to see something happen, e.g.:

const harry = spell("lumos")

After starting your Gatsby dev server you should have a syntax highlighted code block. Now do a right-click on the code block, followed up by a click on Inspect element to view the block in the developer tools. You see something like:

<div class="gatsby-highlight" data-language="js">
  <pre
    class="language-js"
  ><code class="language-js">YOUR_CONTENT_HERE</code></pre>
</div>

You need to target the .gatsby-highlight class and pre tag to add the label via the pseudo-selector ::before.

Create a CSS file and include it in your gatsby-browser.js file. The CSS itself is:

.gatsby-highlight {
  position: relative;
  -webkit-overflow-scrolling: touch;
}
.gatsby-highlight pre[class*="language-"] {
  -webkit-overflow-scrolling: touch;
}
.gatsby-highlight pre[class*="language-"]::before {
  background: black;
  border-radius: 0 0 0.25rem 0.25rem;
  color: white;
  font-size: 12px;
  letter-spacing: 0.025rem;
  padding: 0.1rem 0.5rem;
  position: absolute;
  right: 1rem;
  text-align: right;
  text-transform: uppercase;
  top: 0;
}
.gatsby-highlight pre[class="language-js"]::before {
  content: "js";
  background: #f7df1e;
  color: black;
}

The wrapping div has a relative position so that the tab itself can be positioned absolutely. The CSS also makes use of attribute selectors to target every pre tag with language-* classes. Every language will be targeted by this (your default styling), hence for specific languages you overwrite some of the styling.

If you want to add tabs for other languages, copy the existing language-js version (you can again inspect the DOM before to know what to target).

MDX & prism-react-renderer

When using MDX and gatsby-plugin-mdx you could also use the aforementioned gatsby-remark-prismjs, however MDX offers you more possibilities, so why not use them, e.g. for a live editor?
Set up a new project with npm init gatsby and choose MDX this time. Also install prism-react-renderer. You can copy custom-prism-styles.css from the first quick tip to this project and also import it inside gatsby-browser.js.

To get the CSS from custom-prism-styles.css to work, you'll need to think of adding a div with .gatsby-highlight when using prism-react-renderer.

The main part is to create a <Code /> component and mapping it to the pre tag in MDX. The language-tabs-mdx codesandbox shows the complete setup, here's the code component as a snippet:

import React from "react"
import Highlight, { defaultProps } from "prism-react-renderer"

const Code = () => (
  <Highlight {...defaultProps} code={codeString} language={language}>
    {({ className, style, tokens, getLineProps, getTokenProps }) => (
      <div className="gatsby-highlight" data-language={language}>
        <pre className={className} style={style}>
          {tokens.map((line, i) => (
            <div {...getLineProps({ line, key: i })}>
              {line.map((token, key) => (
                <span {...getTokenProps({ token, key })} />
              ))}
            </div>
          ))}
        </pre>
      </div>
    )}
  </Highlight>
)

export default Code

If you now start the development server and inspect the HTML the extra container will be in the DOM. Should work with the above CSS now, right? Not quite yet, one small adjustment needs to be made. As you can see in the DOM, the pre element now has two classes:

<pre class="prism-code language-js">YOUR_CONTENT</pre>

Therefore the previous pre[class="language-js"] selector won't work anymore as it expects only this one class. By changing this to pre[class~="language-js"] you say: When one of the class names is language-js, please do the following.