Made Mistakes on Made Mistakes

Feeds

2024-06-04T14:36:56-04:00

To receive updates, subscribe to one of Made Mistakes’ web feeds¹ below using your news reader of choice… I like Feedly.

If you’re new to feeds, RSS, Atom and the like, aboutfeeds.com has you covered and explains how to get started. ↩︎

Feeds was originally published on Made Mistakes.

And just like that, I was done with Netlify

2024-02-29T09:53:40-05:00

As someone who uses Netlify’s Starter plan to host this site, the following situation is the kind of nonsense that keeps me up late at night…

On February 24th, an invoice was issued to a Starter plan user of Netlify for a substantial amount of bandwidth usage.

Our internal systems should have identified this rare case, and it should have been flagged by our systems before being sent to this user. We sincerely apologize for this situation and the anxiety it caused. Please know that we are taking this situation very seriously.

This situation has reinforced the urgency of our ongoing work to put safeguards in place in our billing system to ensure that this never happens again. No user of Netlify should ever be concerned that this could happen to them, and we are committed to fixing this issue immediately.

We will also be looking at our company practices, as there clearly was an opportunity for us to have better handled this situation.

Again, we apologize to the impacted user, as well as the community at large. We promise to do better.

Netlify (@Netlify) February 27, 2024

The fact that a small static site hosted for free could potentially cost thousands of dollars is insane. Up until now, I assumed hitting any bandwidth limits would take the site down until the next billing period (or pay any overage fees to turn it back on).

To mitigate the risk of this happening to me, I shut down Netlify deployments and migrated to Cloudflare Pages. On paper Cloudflare’s features are way more attractive and don’t imply free plans will be charged for going over any limits.

Free plan comparison

-	Cloudflare	Netlify
Bandwidth	Unlimited	100GB per month (then $55 per 100GB)
Builds	1 concurrent build, 500 times per month	1 concurrent build, 300 minutes per month (then $7 per 500)
Sites	Unlimited	500
Preview deployments	✔	✔
Custom domains	100 per project	~90 apex domains
SSL certificate	✔	✔
Site analytics	Free	$9 per site per month
Files	Sites can contain 20,000 files — maximum asset size is 25 MiB	Limit of 54,000 files per directory — maximum asset size is 100 MiB
Header rules	Maximum of 100 rules	-
Redirects	Maximum of 2,000 static redirects and 100 dynamic redirects. Bulk Redirects allow for much more at the account level.	No apparent limit, recommended to keep under 10k redirects
Content scraping protection	Protects text, images and email addresses from web scrapers	-
Members	Pages site can be managed by an unlimited number of users via the Cloudflare dashboard	Limited to 1 free member, with unlimited Git Contributors

Cloudflare Pages

Migrating from Netlify to Cloudflare was painless:

Connect GitHub repository to Cloudflare Pages.
Configure Hugo build command.
Validate *.pages.dev site builds when pushing commits to GitHub.
Copy DNS records from Netlify over to Cloudflare.

The hardest part was waiting for all the records to propagate across the internet.

My custom _headers and _redirects files used by Netlify ported over great too as Cloudflare Pages uses the same.

 srcset="https://mademistakes.com/images/cloudflare-pages-mm-build-log_hu916490700792609871.jpg 300w, https://mademistakes.com/images/cloudflare-pages-mm-build-log_hu3322410832660247704.jpg 620w"
>

One snag I encountered during the migration was long build times. In my previous workflow, I set up GitHub Actions and Netlify to cache all generated static assets between builds. For a site like mine with thousands of images, this slashes a cold build from 18 minutes down to a minute for incremental builds.

 srcset="https://mademistakes.com/images/cloudflare-build-cache-beta_hu13344641167702600729.jpg 300w, https://mademistakes.com/images/cloudflare-build-cache-beta_hu12578056594562643106.jpg 620w"
>

Cloudflare Pages does support build caching, but only for Gatsby, Next.js, and Astro frameworks. It’s a beta feature, so I expect Hugo to be added in the future. For now I’ll have to live with 18-minute builds — unless I decide to use a GitHub Action again to build then deploy to Cloudflare using their Wrangler CLI. We’ll see…

 srcset="https://mademistakes.com/images/cloudflare-mm-web-analytics_hu1359105835052311903.jpg 300w, https://mademistakes.com/images/cloudflare-mm-web-analytics_hu8296939172255951730.jpg 620w"
>

Another bonus, Cloudflare gives you privacy-first site analytics for free too. Which could be an option if I decide Google Analytics at some point.

And hell, if Cloudflare Pages turns out to be a dud or too restrictive I can always go back to self-hosting on the cheap.

And just like that, I was done with Netlify was originally published on Made Mistakes.

DIY record cube back spacers

2024-02-22T00:00:00-05:00

For the longest time, it has driven me mad that my records get out of alignment any time I slide one out to play. To solve this problem, Turntable Revival sells wooden back spacers for cube shelves (Ikea Kallax, Target Threshold, Walmart - Better Homes & Gardens) to straighten your records out.

To save a buck I decided to MacGyver a cheap solution with black foam board and double-sided tape.

Procedure

Step 1: Measure the length of each cube. I have two 6-cube Target Threshold organizers, with each cube measuring 13 ½" wide.

Measure the empty shelf space to determine the back spacer’s size.

Step 2: Grab a record, place it to the far left and align it with the cube’s back edge. Then measure the distance from the record’s spine to the front of the cube. For my shelving, this ended up being 2" deep.

Step 3: With a ruler and a pencil add guidelines to the foam board and use a sharp utility blade to cut the spacers.

I took a 16" x 20" foam board, cut the shorter side down to 13 ½" and then cut that down at 2" intervals — ending up with 10 back spacers.

Step 4: Using rubbing alcohol and a paper towel, clean the bottom side of each cube you’re adding a spacer to. Once dry, cut a strip of double-sided tape for each spacer and remove one side of the backing.

Place the tape (sticky side down) onto the spacer and run your finger over it to make a good connection. Then remove the top piece of backing and place the spacer into the shelf making sure its edge is aligned with the back of the cube.

Press down firmly on the foam board, using a circular motion to fully adhere the tape to the shelf.

Step 5: Slide a record into the cube shelf and verify you are happy with the placement. Repeat the process for the remaining cubes.

DIY record cube back spacers was originally published on Made Mistakes.

Goodbye Gatsby, Hello Hugo

2023-01-14T14:06:05-05:00

Personal sites are a great testing ground for mixing it up and experimenting. Back when Gatsby first started buzzing in Jamstack circles, I used that as my excuse to migrate off Jekyll and learn something new.

As someone who avoids writing JavaScript whenever possible, there were considerable growing pains as dug into the React, GraphQL, and NPM ecosystems. It took time, but I got the site to a place on par with what I had achieved with Jekyll.

As I used Gatsby more, the reliance on plugins started frustrating me. External dependencies lagging behind Gatsby made updating a chore, and in the case of migrating to Gatsby 5 — impossible.

For example, critical remark plugins related to Markdown parsing became stuck blocking me from upgrading, unless I wanted to stop using them… which I didn’t.

Static site generator choices

So I started looking around. Jekyll seemed like a logical choice, but returning to Ruby… no thanks. Not to mention the appearance of Jekyll fizzling out wasn’t doing it any favors.

Eleventy (11ty) is what all the cool kids are using, and it shares a lot of Jekyll-isms. And then there is Hugo, which made a splash years back when Smashing Magazine switched from WordPress to it. Maybe these were good static site generators to explore?

For a few weeks, I worked on a proof of concept, migrating layouts and content from Gatsby over to 11ty. It all felt Jekylly but with added flexibility and none of the Ruby pain.

Then I encountered a roadblock (more of a detour) with collections and how 11ty uses tags to assign them. I’m sure I could have worked around it, but conceptually it clashes with how I organize content: categories as sections > tags for loosely related topics.

On the other hand, Hugo seemed purpose-built for me. Full of strong conventions on how to do things, but with enough flexibility to bend as needed. This was a stark contrast with what I had experienced trying to organize and write content with Gatsby, 11ty, and to a lesser degree Jekyll. With those SSGs, I often felt like I was rolling my own solution to do something that should be standard.

Feature comparisons

Want to dump a bunch of Markdown files in a folder with a sprinkling of front matter… you can. But if you want to level up, Hugo offers up ways of bundling pages into sections alongside resources so you can keep your content nice and tidy.

When following conventions Hugo expects, the file structure is used to inform a page’s section, content type, whether a branch or leaf node, its layout, and more. Making the building of menus, breadcrumb navigation, list pages, and pagination straightforward as they are fully integrated into Hugo’s core features.

Building basic blog sites with posts listed in reverse chronological order, it’s easy to miss out on all that Hugo offers. And to be honest, unless you have prior experience with static site generators or fully read through Hugo’s (at times obtuse) documentation, you can miss out on the benefits of having the following features.

Markdown render hooks

Coming from Gatsby, I now expect all static site generators to take image references written in Markdown and spit out resized versions with appropriate responsive srcset markup.

I give you this:

![Chicken wings covered in hot sauce](chicken-wings.jpg)

You give me this:

<img alt="Chicken wings covered in hot sauce" src="chicken-wings.jpg" srcset="chicken-wings-300.jpg 300w, chicken-wings-600.jpg 600w, chicken-wings-900 900w" sizes="(max-width: 900px) 100vw, 900px" loading="lazy" decoding="async" width="900" height="600">

I fought with Jekyll for years trying to do this. The common pitfalls are:

Image assets live outside of your _posts or collection folders. Linking to them with relative paths in Markdown files is more difficult than it should be.
Every Jekyll responsive images plugin I tried used some flavor of ImageMagick to convert images. ImageMagick is slow and slogging through thousands of files crushed my build times. You can sort of get around this by using a combination of Sharp and Gulp, but it hardly feels like the Jekyll way.
Using Liquid tags e.g., {% responsive_image path: chicken-wings.jpg alt: "Chicken wings covered in hot sauce" %} is less than ideal if you’re committed to an all-Markdown workflow. A pre_render hook plugin that replaces Markdown image references with an appropriate {% responsive_image %} tag can get around this, but feels hacky.

11ty with the Sharp-based eleventy-img plugin and a custom image renderer for markdown-it can get you closer. Still, for me, there was enough flakiness going on — missing images and random build crashes — encouraging me to look elsewhere. It’s an open issue, so here’s hoping that someday there will be an enhancement to improve it.

Then there’s Hugo, which lets you customize how Markdown outputs to HTML with what it calls render hooks. These render hook templates are standard HTML with the same templating logic used to write shortcodes, partials, and layouts. Something I appreciate, as writing HTML comes more naturally to me than JavaScript or Ruby.

I’m using a render hook (render-image.html) to process Markdown images into responsive image markup like so:

{{- $sizes := (slice "300" "768" "1024" "1280") -}}
{{- /* Get file that matches the filename as specified as src="" */ -}}
{{- $src := .Page.Resources.GetMatch .Destination -}}
{{- if and (not $src) .Page.File -}}
 {{- $path := path.Join .Page.File.Dir .Destination -}}
 {{- $src = resources.Get $path -}}
{{- end -}}
{{- $alt := .PlainText | safeHTML -}}

{{- /* Conditional for resources that aren't in page bundle. */ -}}
{{- if $src -}}
 {{- $color := delimit (first 1 $src.Colors) "" -}}
 <img sizes="(min-width: 1440px) 690px, (min-width: 1024px) 790px, 94vw"
 srcset="
 {{- range $sizes }}
 {{- if ge $src.Width . }}{{ ($src.Resize (printf "%sx" .)).RelPermalink }} {{ (printf "%sw" .) }}, {{ end }}
 {{- end -}} {{ $src.RelPermalink }} {{ $src.Width }}w"

 {{- /* If smaller than 768px wide, then load the original */ -}}
 {{ if ge $src.Width "768" }} src="{{ ($src.Resize "768x").RelPermalink }}"
 {{ else }}src="{{ $src.RelPermalink }}"
 {{- end -}}
 alt="{{ $alt }}" loading="lazy" decoding="async" width="{{ $src.Width }}" height="{{ $src.Height }}" {{ if ne $src.MediaType.SubType "png" }}style="background: {{ $color }}"{{- end -}}
 />
{{- else -}}
 <img src="{{ .Destination | safeURL }}" alt="{{ $alt }}" loading="lazy" decoding="async" />
{{- end -}}

Add anchor links (render-heading.html) to headings:

<h{{ .Level }} id="{{ .Anchor | safeURL }}">
 <a href="#{{ .Anchor | safeURL }}" title="Permalink to {{ .Text | plainify }}">{{ .Text | safeHTML }}</a>
</h{{ .Level }}>

And add a rel="noopener" attribute to external links (render-link.html):

<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

Archetype templates

I write new posts so infrequently that it’s not uncommon for me to forget the names of front matter fields used in site layouts. To get around this I clone a starter Markdown document with a pre-configured placeholder front matter and draft a new post from that.

Hugo improves on this with the concept of archetypes — directory-based template files used for creating new content.

Archetype templates look a lot like one of my starter .md files but with template logic and variables to pre-populate front matter fields like title and date.

When running the hugo new command to create a new file, an appropriate archetype is used based on the document’s file path. This flexibility allows you to have different sets of archetype templates based on content type or section.

My /archetypes/default.md template looks like this:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
last_modified_at:
draft: true
description:
image:
toc:
---

Which when used with hugo new notes/my-new-note.md generates a new Markdown file with the following starter contents:

---
title: "My New Note"
date: 2023-01-12T14:04:39-05:00
last_modified_at:
draft: true
description:
image:
toc:
---

The simplicity of creating templates in the same YAML and Markdown format as the rest of the site content makes a ton of sense to me. While other static site generators require: a content management system, scripts, task runners, or in Jekyll-land the jekyll-compose Ruby gem — to do what Hugo does natively.

Taxonomies

If you use taxonomies like categories or tags to group content, the popular SSGs have you covered as Jekyll has collection support to do custom grouping, but it’s not as robust as what Hugo offers.

11ty also has collections but confusingly calls them tags, which is inconvenient if you’re coming from Jekyll or any other blogging platform.

Gatsby has no concept of categories or tags and it is up to you to structure, organize, assign relationships, and write custom logic to filter content. I had a hell of a time writing my gatsby-node.js file to generate paginated archive pages for categories and tags.

And then there is Hugo, which automatically creates taxonomy pages for categories and tags. If that’s not enough for you, Hugo also natively supports:

Creating custom taxonomies to handle relationships other than categories and tags.
Ordering of taxonomies by weights allows the same piece of content to appear in different positions in different taxonomies.
Adding metadata to a taxonomy or term, something I used to hack together with YAML data files in Jekyll and Gatsby.

Content excerpts

Gatsby, Jekyll, and Hugo all have support for automatically creating shortened excerpts of a page’s main content to be used as teaser/preview text in RSS feeds, meta descriptions, and the like. Each of these SSGs uses separators to mark what part of the content should be used as an excerpt.

Gatsby (via gatsby-transformer-remark) allows you to configure the length of excerpts and their format (plain text, HTML, or Markdown).
Jekyll uses the first paragraph as an excerpt.
Hugo calls them content summaries and uses the first 70 words as an excerpt.

11ty requires front matter customizations to parse excerpts and separators from content to function how the three SSGs above do.

Image processing

Gatsby, Hugo, and 11ty all support image processing. Gatsby has the advantage if you’re using components as it can do responsive images with trendy loading effects like blur up, background color, and traced SVG via props and GraphQL queries.

On the flip side, if you’re bringing your own HTML and need a utility to transform and manipulate images — Hugo and 11ty have you covered.

The differences come down to how images are processed and rendered:

Gatsby has React image components and the magical black box that is gatsby-remark-images.
11ty has eleventy-img which can be used in layouts and shortcodes.
Hugo has image filters you can weave into layouts, shortcodes, and render hooks.

No surprise here, but I prefer the Hugo way. Using variables and piping on filters feels more natural than GraphQL queries and JavaScript. For example, a feature image defined in the front matter can be transformed (resized to 600px wide) like so:

{{ $source := .Page.Resources.GetMatch .Params.feature }}
{{ $image := $source.Resize "600x" }}
<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}" alt="">

Adjusting an image’s hue, brightness, sharpness, and adding overlays are a set of filters away with Hugo.

Colors

I started using Hugo’s new colors method to return the dominant colors of an image. I then limit this array to the first value and set it as a background-color to serve as a low quality image placeholder (LQIP) before it fully loads.

Don’t worry, I’m also setting a width and height on all images to avoid layout shifts during load.

 srcset="https://mademistakes.com/images/mm-gallery-lqip-screenshot_hu14623935192140083533.jpg 300w, https://mademistakes.com/images/mm-gallery-lqip-screenshot_hu14060119479471555584.jpg 620w"
>

To encourage browsing, I include links to related content at the end of each post. I’ve managed these groupings and relationships:

Manually in the front matter.
Automatically with plugins.

Thankfully, both Hugo and Jekyll have built-in methods for accessing related content automatically.

Hugo can list a page’s related content based on the front matter parameters you define. While Jekyll’s related posts module uses classifier-reborn to create relationships, is limited to the posts collection, and is slow.

Each can be looped through using Go and Liquid:

Related posts via Go:

{{ $related := .Site.RegularPages.Related . | first 3 }}
{{ with $related }}
 <h3>Related posts</h3>
 <ul>
 {{ range . }}
 <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
 {{ end }}
 </ul>
{{ end }}

Related posts via Liquid:

{% if site.related_posts.size >= 1 %}
 <h3>Related posts</h3>
 <ul>
 {% for related_post in site.related_posts limit: 3 %}
 <li><a href="{{ related_post.url }}">{{ related_post.title }}</a></li>
 {% endfor %}
 </ul>
{% endif %}

With Gatsby, I struggled with GraphQL queries and an earlier version of gatsby-remark-related-posts to automatically determine related posts. From the documentation, version 2 of the plugin seems to have improved on the clunkiness. But I can’t verify if that’s true as I haven’t tried upgrading yet.

11ty didn’t appear to have a native way of listing related content. Methods I dug up involved manual effort and maintenance — add tags to content in the front matter then filter on those tags.

Automatic table of contents

Gatsby’s remark transformer, Jekyll via a Kramdown {: toc} reference, 11ty plugin eleventy-plugin-toc, and Hugo all take Markdown files and generate a table of contents from the headings. Useful for creating jump links to skip lengthy bits of content.

Conclusion

If it wasn’t clear already — I ditched Gatsby and migrated this site over to Hugo. Hugo is often viewed as the fastest static site generator… it is.

It excels at content management, with a flexible organizational structure, multilingual mode, and menu system that all integrate with one another. It is clear that Hugo’s maintainers carefully consider each feature and how they should work together.

Hugo has ruined me. Other static site generators that rely on community plugins and copypasta to fill out their gaps don’t cut it anymore…

Goodbye Gatsby, Hello Hugo was originally published on Made Mistakes.

Adding last modified timestamps with Git

2021-08-04T20:34:59-04:00

A common ask of Jekyll, Gatsby, and other static site generator users is, “how do I automatically set the date in YAML front matter?” Today I learned you can do just that with a Git pre-commit hook.

If your project has been setup with git init you should have a Git hooks directory with several sample files to inspect.

├── .git
│ └── hooks
│ ├── applypatch-msg.sample
│ ├── commit-msg.sample
│ ├── post-update.sample
│ ├── pre-applypatch.sample
│ ├── pre-commit.sample
│ ├── ...

You can either create a new file named pre-commit inside of the hooks directory (or rename the .sample file). Then add the following shell script:

#!/bin/sh
# Contents of .git/hooks/pre-commit
# Replace `last_modified_at` timestamp with current time

git diff --cached --name-status | egrep -i "^(A|M).*\.(md)$" | while read a b; do
 cat $b | sed "/---.*/,/---.*/s/^last_modified_at:.*$/last_modified_at: $(date -u "+%Y-%m-%dT%H:%M:%S")/" > tmp
 mv tmp $b
 git add $b
done

Now when you commit a modified file with Git, the value of last_modified_at will be replaced with the current time i.e., YYYY-MM-DDThh:mm:ss. If you’re using a different front matter variable for modified timestamps, adjust the script above accordingly.

Before commit	After commit
`last_modified_at:`	`last_modified_at: 2021-08-04T20:34:59`

I’ve always followed the convention of using date for published timestamp and last_modified_at for the modified timestamp. Mostly because core Jekyll plugins like jekyll-sitemap and jekyll-feed support that front matter value.

---
title: "My awesome Markdown post"
date: 2020-01-01
last_modified_at: 2021-08-04T20:34:59
---

I’d be interested if the script could be improved on to append the date if last_modified_at hasn’t already been added, and replace the value if it has. Let me know below if you have any improves there.

I’m also not sure if this pre-commit hook is automatically installed when the Git repository is cloned. Do I need to install it on both my iMac running macOS and laptop running Windows 10? Or does it come along for the ride when push/pulling from remote?

Adding last modified timestamps with Git was originally published on Made Mistakes.

URLs and links in Jekyll

2021-07-20T10:22:43-04:00

Before you can link pages and assets together with Jekyll, you need to know how it assigns URLs (or permalinks¹) to each. If you are a seasoned Jekyll users and have a good understanding of how this all works, skip down below to linking methods.

This tutorial will explain the various URL types, how to use them when building with Jekyll, and then how to link content and assets together.

How URLs work in Jekyll

Jekyll’s system for creating URLs is simple and flexible, allowing you to structure files how you want. That is…once you understand how permalinks work for posts, pages, collection documents, and static files.

Below are the core concepts and conventions you’ll need to get started with each. For an exhaustive list of possible URL patterns and styles, be sure to read Jekyll’s permalink documentation.

Global permalinks

Changing the global output path for posts and pages is one of the first settings you’ll configure in _config.yml. The default pattern used by Jekyll is permalink: date, which is short for:

permalink: /:categories/:year/:month/:day/:title:output_ext

This permalink pattern is made up of the :categories, :year, :month, :day, :title, and :output_ext placeholders. For an entire list of placeholders review Jekyll’s placeholder documentation.

Placeholder	Description
`categories`	Assigned categories for a post from its YAML front matter. Multiple categories e.g., `categories: [development, CSS]` would output as `/development/css`.
`year`	Year value (four digits e.g., `2021`) from the post’s filename.
`month`	Month value (two digits `01` through `12`) from the post’s filename.
`day`	Day value (two digits `01` through `31`) from the post’s filename.
`title`	String from the document’s filename.
`output_ext`	Extension of the output file, usually `.html`.

In addition to the date permalink, Jekyll has the following patterns built-in for posts. Note: date based placeholders are ignored for documents like pages and collections.

Permalink alias	Permalink pattern
`date`	`/:categories/:year/:month/:day/:title:output_ext`
`pretty`	`/:categories/:year/:month/:day/:title/`
`ordinal`	`/:categories/:year/:y_day/:title:output_ext`
`weekdate`	`/:categories/:year/W:week/:short_day/:title:output_ext`
`none`	`/:categories/:title:output_ext`

URL defaults

When building a fresh Jekyll site using the jekyll new command, the following URL defaults apply. The same is true if your _config.yml omits the permalink configuration as Jekyll falls back to the /:categories/:year/:month/:day/:title:output_ext.

Post URL defaults

Posts are a special collection in Jekyll and have filename requirements as described in their posts documentation. Because of this YYYY-MM-DD-title.ext convention, Jekyll is able to determine a post’s title and date without either being manually added via YAML front matter.

For example, let’s create a new Markdown post and name it 2021-06-30-new-post.md, making sure it’s in the _posts directory.

├── _posts
│ └── 2021-06-30-new-post.md

Jekyll knows the title of this post is new post and the date is 2021-06-30 for the reasons stated above.

When Jekyll builds the site it will use the default permalink pattern of permalink: date and output a HTML file into the _site directory with a root-relative URL of /2021/06/30/new-post.html.

├── _site
│ └── 2021
│ └── 06
│ └── 30
│ └── new-post.html

Posts (unlike pages and other collections) have complete support for categories, which become part of their URL when using the default permalink pattern.

Using the example post created above and adding categories to it via YAML front matter:

---
categories: ["development", "CSS"]
---

The resulting URL would become /development/css/2021/06/30/new-post.html with this file structure:

├── _site
| └── development
| └── css
│ └── 2021
│ └── 06
│ └── 30
│ └── new-post.html

Page URL defaults

A common Jekyll page convention is to add HTML or Markdown files in the root directory. In fact when running the jekyll new command it scaffolds out the following two pages in the root:

├── about.markdown
├── index.html

When Jekyll builds the site it will use the default permalink pattern of permalink: date and output two HTML files into the _site directory with root-relative URLs of /about.html and /index.html.

├── _site
| └── about.html
| └── index.html

Don’t let `permalink: date` fool you

Because pages are not date based like posts, even if you add a date via YAML front matter to about.md like so:

---
date: 2021-07-07
---

It will not output the file into a year/month/day directory structure. You’ll still end up with:

├── _site
| └── about.html

Note: There are other inconsistencies between posts, collections, and pages that have been documented in this GitHub issue.

Pages can be organized into sub-directories and Jekyll will respect that structure and output matching folders and files. For example, if we create a page named privacy-policy.md and place it a directory named terms.

├── terms
│ └── privacy-policy.md

When Jekyll builds the privacy policy page it will output a HTML file into the _site directory with a root-relative URL of /terms/privacy-policy.html.

├── _site
│ └── terms
│ └── privacy-policy.html

Collection URL defaults

Collection documents have a default permalink style of permalink: /:collection/:path when output: true is enabled. These files output in a similar way to pages. Meaning they ignore some permalink placeholders like categories.

For example, if we create a collection named recipes with the following minimal configuration:

collections:
 recipes:
 output: true

And then create two documents — apple-pie.md and minestrone.md, and place them in the _recipes directory.

├── _recipes
│ ├── apple-pie.md
│ └── minestrone.md

When Jekyll builds the site it will use the default permalink pattern of permalink: /:collection/:path and output two HTML files into the _site directory with root-relative URLs of /recipes/apple-pie.html and /recipes/minestrone.html.

├── _site
│ └── recipes
│ ├── apple-pie.html
│ └── minestrone.html

Collection documents can be organized into sub-directories (just like pages) and Jekyll will respect that structure and output matching folders and files.

For example, if we group the apple pie and minestrone recipes into deserts and soups directories inside of _recipes:

├── _recipes
│ ├── deserts
│ │ └── apple-pie.md
│ └── soups
│ └── minestrone.md

Now when Jekyll builds the site these two recipes will output into the following structure:

├── _site
│ └── recipes
│ ├── deserts
│ │ └── apple-pie.html
│ └── soups
│ └── minestrone.html

Static file URL defaults

Files that do not contain any YAML front matter (aka static files), Jekyll outputs in the same structure it sourced from. This applies to images, videos, PDFs, and other assets that aren’t processed via Jekyll’s Sass and CoffeeScript pipelines.

Like pages and collection documents, static files can be organized in whichever way you choose and Jekyll will match naming and structure. For example, if we have a image named logo.png and place it in a static/images sub-directory.

├── static
│ └── images
│ └── logo.png

When Jekyll builds the site it will and output the logo into the _site directory with a root-relative URL of /static/images/logo.png.

├── _site
│ └── static
│ └── images
│ └── logo.png

File specific permalinks

Permalinks can be set in a file’s YAML front matter, overriding globally set patterns in the _config.yml file. Organizing files in a _pages² folder and outputting them with a root-relative URL is a common use case.

For example, if we create a resume.md page and place it in a _pages subdirectoy.

├── _pages
│ └── resume.md

When Jekyll builds the site it will output the resume page into _pages/resume.html which isn’t what we’re looking to achieve. We’d much rather it end up in pages/resume.html without the leading _.

You could of course rename the _pages directory to pages and get the desired result. But if you’re looking to follow the convention of naming Jekyll source directories with underscores, then setting a permalink override is the solution.

Inside of _pages/resume.md we can add the following path to force where it outputs to.

---
permalink: /resume.html
---

Now when Jekyll builds the site it will output the resume page into:

├── _site
│ └── resume.html

We can even change the filename it outputs as:

---
permalink: /resume/index.html
---

Duplicate permalinks

Different source files with the same permalink can cause all sorts of confusion when troubleshooting a Jekyll build. Maybe you made some changes to your home page’s content and can’t figure out why it’s not updating. Or maybe you see nothing at all and the page is blank.

This is quite common when forking or copying other Jekyll repositories and ending up with both index.html and index.md files in your project. Since they share a filename, they’ll output to the same location and conflict 💥.

This could also happen if you had a file like _pages/home.md with permalink: / or permalink: index.html added to its YAML front matter. Thankfully in newer versions, Jekyll’s CLI will warn you about such conflicts.

Conflict: The following destination is shared by multiple files.
The written file may end up with unexpected contents.
C:/Users/michael/sites/jekyll-site/_site/index.html
 - home.md
 - index.md

How to link

How do you link posts, pages, documents, images, videos, and other resources together with Jekyll? Before answering that question, it’s useful to learn about the following URL types:

URL types

	Type	Description
1	Document-relative	URL contains path relative to the current page.
2	Root-relative	URL contains path relative to the site’s root directory — starts with a forward slash `/`.
3	Absolute	Full URL including protocol, domain, port, and or path.

Document-relative URLs

A relative URL that does not start with /, is document-relative and will instruct the browser to look for the document or file in the context of the current page.

Meaning if the browser has the following page open: https://mademistakes.com/articles/index.html, and there is a document-relative link pointing to article-two/index.html it would browse to the article-two sub-directory inside of the articles directory. Then look for a file named index.html.

├── https://mademistakes.com/articles
│ └── index.html (current document)
│ └── articles-two
│ └── index.html

When do you use document-relative URLs?

In my experience document-relative URLs are not all that common when working with Jekyll unless you have a flat directory structure. The one use case where I think they are helpful is if you want to organize supporting assets with a post in the same directory.

├── _posts
│ └── 2021-07-12
│ ├── 2021-07-12-weeknotes-8.md
│ ├── bbq.jpg
│ └── fireworks.jpg

Unfortunately Jekyll doesn’t make this easy out of the box as it doesn’t know what to do with the non-Markdown files above.

2021-07-12-weeknotes-8.md would be read and output as expected to _site/2021/07/12/weeknotes-8.html, but the static assets bbq.jpg and fireworks.jpg would not.

With the help of Nicolas Hoizey’s jekyll-postfiles plugin this can be fixed. Once installed, static assets will follow the same permalink pattern as posts and output alongside them like this:

├── _site
│ └── 2021
│ └── 07
│ └── 12
│ ├── weeknotes-8.html
│ ├── impossible-burgers.jpg
│ └── fireworks.jpg

Now we can add document-relative links to images (or other assets) in Markdown and HTML files without them 404ing.

![Impossible burgers on the grill](impossible-burgers.jpg)

<img src="fireworks.jpg" alt="Fireworks exploding in the sky">

Root-relative URLs

As the name implies, root-relative URLs make the path relative to the root directory of the site, denoted by a forward slash /.

Meaning if the browser has the following page open: https://mademistakes.com/about/index.html, and there is a root-relative link pointing to /legal/privacy-policy/index.html it would browse to the legal directory from the root directory. Then down into the privacy-policy sub-directory, where it would open a file named index.html.

├── https://mademistakes.com
│ ├── about
│ │ └── index.html (current document)
│ └── legal
│ └── privacy-policy
| └── index.html

The forward slash / is import as it starts from the root of the server. If the / was omitted and the link was legal/privacy-policy.html, the browser would try to open https://mademistakes.com/about/legal/privacy-policy/index.html instead. Which would lead to a 404 error page as this file does not exist on the server.

When do you use root-relative URLs?

Root-relative are most often used to link internal pages (e.g., related posts, category and tag archives, an about page, etc.) from the same site together. In my experience they are helpful when building sites with a deep directory structure.

It’s much easier to avoid broken links and 404 pages this way as you don’t have to worry page context when crafting URLs.

Some examples of root-relative URLs are:

[root-relative file](/root-relative-file.html)

<!-- anchor link -->
<a href="/root-relative-file.html">root-relative file</a>

<!-- sitemap -->
<link href="/sitemap.xml" rel="sitemap" type="application/xml">

<!-- JavaScript file -->
<script src="/app.js"></script>

Absolute URLs

Unlike relative URLs, absolutes or full URLs have all of the necessary elements (protocol, domain, port, and path) needed to resolve a URL.

When do you use absolute URLs?

Absolute URLs are used when linking to pages and files that live outside of the current site.

For example, the about page on this site links out to Twitter with the following absolute URL https://twitter.com/mmistakes which contains the protocol https://, domain twitter.com and path of /mmistakes.

Some examples of absolute URLs are:

[file on another domain](https://not-mademistakes.com/absolute-file.html)

<!-- external anchor link -->
<a href="https://not.mademistakes.com/absolute-file.html">absolute file</a>

<!-- externally hosted CSS file -->
<link href="https://not.mademistakes.com/assets/styles.min.css" rel="stylesheet">

<!-- externally hosted JavaScript file -->
<script src="https://not.mademistakes.com/assets/app.js"></script>

About `site.url` and `site.baseurl`

These two Jekyll _config.yml variables are notorious for breaking links, stylesheets, JavaScript and more. Knowing how they function is important for building working relative and absolute URLs in Jekyll theme files like layouts and includes.

Linking posts

There are multiple ways to link to other Jekyll posts:

Reference the post’s full root-relative URL e.g., /2021-01-01-how-to-make-pizza.html.
Use Jekyll’s {% post_url %} tag.
Use Jekyll’s {% link %} tag.

The best way I’ve found is to use Jekyll’s {% post_url %} tag as it generates the correct URL even if the permalink style changes — baseurl folder and all.

`{% post_url %}` and `{% link %}` tags

Jekyll comes with a set of Liquid tags that makes linking easier for content authors and editors. If following the Jekyll convention of organizing posts in the _posts folder…

├── _posts
│ ├── 2021-01-01-how-to-make-pizza.md
│ └── 2021-05-20-birthday-bash.md

You’d link to post 2021-01-01-how-to-make-pizza by referencing its filename, omitting the extension at the end, e.g., .md.

{% post_url 2021-01-01-how-to-make-pizza %}

Jekyll will then output the following root-relative URL (if using the default permalink pattern of permalink: date.)

/2021/01/01/how-to-make-pizza.html

Jekyll also has the {% link %} tag, which can be used to link to a post, page, collection document, or file. The big difference between link and post_url is that the link tag requires the file’s full path e.g., directory and extension.

Using the same “How to make pizza” post from above, here’s how to link to it using Jekyll’s link tag:

{% link _posts/2021-01-01-how-to-make-pizza.md %}

Jekyll then outputs the same root-relative URL as before, /2021/01/01/how-to-make-pizza.html.

For links created using either {% post_url %} or {% link %}, if the baseurl config has been set because the site is hosted on GitHub Pages, for example something like this:

# _config.yml
basewebsite: /project-name

Jekyll will output this root-relative URL instead: /project-name/2021/01/01/post-to-link-to.html.

⚠ `post_url` and `link` with `baseurl`

Jekyll sites build with version 3.0 and configured with a baseurl, need to prepend post_url or link tags with site.baseurl like this:

{{ site.baseurl }}{% post_url 2021-01-01-how-to-make-pizza %}
{{ site.baseurl }}{% link _posts/2021-01-01-how-to-make-pizza.md %}

Check these baseurl URL examples if you’re still unsure on how to set them up.

Pro tip: Link validation

Using the {% post_url %} tag has the added benefit of letting you know if the post linked to is valid. If a post was renamed or removed this would help identify a potential 404 error before being pushed into production.

Could not find post "2099-01-01-welcome-to-the-future.markdown" in tag 'post_url'. (Jekyll::Errors::PostURLError)
Make sure the post exists and the name is correct.

Post link examples

Creating internal links to other posts is the quickest when written in Markdown as it doesn’t require as much markup. If you know a post’s full path you can reference that entire URL or use Jekyll’s post_url or link tags that reference the source file.

[How to make pizza](/2021/01/01/how-to-make-pizza.html)
[How to make pizza]({% post_url 2021-01-01-how-to-make-pizza %})
[How to make pizza]({% link _posts/2021-01-01-how-to-make-pizza.md %})

Or if you prefer to create links in HTML instead, you can.

<a href="/2021/01/01/how-to-make-pizza.html">How to make pizza</a>
<a href="{% post_url 2021-01-01-how-to-make-pizza %}">How to make pizza</a>
<a href="{% link _posts/2021-01-01-how-to-make-pizza.md %}">How to make pizza</a>

Either way you create the link, Jekyll outputs the same HTML:

<a href="/2021/01/01/how-to-make-pizza.html">How to make pizza</a>

`post_url` and permalinks

The post_url tag respects file specific permalinks set in YAML front matter. Meaning if you have a Markdown link like [How to make pizza]({% post_url 2021-01-01-how-to-make-pizza %}) and this front matter:

---
permalink: how-to-make-pizza.html
---

Jekyll will respect the permalink override set in front matter and output the following link:

<a href="/how-to-make-pizza.html">How to make pizza</a>

Linking pages

Like posts, pages can be linked to in multiple ways:

Reference the page’s full root-relative URL e.g., /about.html.
Use Jekyll’s {% link %} tag.

My preferred method is to use Jekyll’s {% link %} tag as it has permalink “smarts” built into it and will warn you if trying to link to an invalid path.

Let’s say you created a fresh Jekyll site using the jekyll new command. After running that, you’d find an about.markdown file in the root of the site:

├── _posts
├── _config.yml
├── about.markdown
├── index.html

To link to that page you could create the link yourself if you know that the output path will be /articles.html. But what if you’re new to Jekyll and not sure how permalinks work?

Page link examples

Jekyll’s link tag solves this problem. All you need to know is the path (i.e., the source file), and then it can be linked like this:

{% link about.markdown %}

With files that are nested in sub-directories, you include the full path. For example, if we have a privacy policy page inside of a /terms directory:

├── terms
│ └── privacy-policy.md

It can be linked to like this (with or without the leading forward slash /) in Markdown or HTML:

[Privacy policy]({% link terms/privacy-policy.md %})

<a href="{% link terms/privacy-policy.md %}">Privacy policy</a>

Jekyll will output the same HTML for both:

<a href="/terms/privacy-policy.html">Privacy policy</a>

Like the post_url tag, if you link to a file that doesn’t exist or use the wrong path — Jekyll will warn you:

Liquid Exception: Could not find document 'terms/privacy-policy.md' in tag 'link'. Make sure the document exists and the path is correct. in index.markdown

Jekyll URL filters

For theme developers and anyone looking to build or modify layouts, Jekyll has a set of Liquid filters that make working with URLs easier. If you’re new to Liquid (the template language used by Jekyll), filters are used to change the output of a string, object, or variable.

You will find them inside of double curly braces {{ }} and after the pipe character |. For example this page.lang variable that has a filter applied to it to assign a default value of "en".

{{ page.lang | default: "en" }}

-	Filter	Description	Example output
Relative URL	`relative_url`	Prepends `baseurl` configuration value to the input creating a relative URL. Recommended for sites placed in a sub-directory e.g., projects hosted on GitHub Pages.	`/my-project/assets/styles.css`
Absolute URL	`absolute_url`	Prepends `url` and `baseurl` configurations values to the input creating an absolute URL.	`https://mmistakes.github.io/my-project/assets/styles.css`

The relative_url and absolute_url filters were created to ease the pain of prepending url and baseurl to links. Instead of needing to write {{ site.baseurl }}assets/css/styles.css. You could write the following:

{{ 'assets/css/styes.css' | relative_url }}

Or if you needed to output the full URL of a page and were using something like: {{ site.url }}{{ site.baseurl }}{{ page.url }} or {{ page.url | prepend: site.baseurl | prepend: site.url }} in your layouts.

Both could be shortened by using Jekyll’s absolute_url filter:

{{ page.url | absolute_url }}

Since filters are generally used in Jekyll layouts and includes, it’s unlikely content authors will have much use for them. In that case, the {% post_url %} and {% link %} tags will be more useful when creating internal links.

Jekyll relative links plugin

Another option for dealing with relative links may be to install the jekyll-relative-links plugin.

Perhaps you have repository of Markdown files on GitHub with links like [foo](bar.md). On GitHub.com these links are valid and work. But on the documentation site you built using these same Markdown source files — the links are broken.

Using the jekyll-relative-links plugin can solve this by converting relative links to Markdown files into links to the appropriate Jekyll generated .html files.

For example, say we have two Markdown files in the root directory:

├── install.md
├── upgrade.md

And in install.md there is the following Markdown that links to upgrade.md:

To [upgrade the package](upgrade.md), run...

On GitHub.com the link will work as expected since upgrade.md exists. But for a Jekyll built site, the browser expects the URL to be something like /upgrade.html (or whatever permalink style is configured).

HTML output	-
`<a href="upgrade.md">upgrade the package</a>`	❌

With jekyll-relative-links installed the same Markdown link of [upgrade the package](upgrade.md) will output as a valid relative link to the rendered file — custom permalinks and all!

HTML output	-
`<a href="/upgrade.html">upgrade the package</a>`	✅

⚠ Compatibility with posts

By default jekyll-relative-links is enabled for pages only. To allow relative links in posts and other collections, set collections to true in the _config.yml file:

relative_links:
 collections: true

Wikipedia describes a permalink or permanent link as a URL that is intended to remain unchanged for many years into the future, yielding a hyperlink that is less susceptible to link rot. ↩︎
Unlike the _posts directory, _pages is not initially recognized by Jekyll. By design, directories (or folders) starting with an _ are ignored except for _includes, _layouts, _posts, and _sass. To force Jekyll to read from these “ignored” directories, add them to the include array within _config.yml. ↩︎

URLs and links in Jekyll was originally published on Made Mistakes.

Jekyll’s site.url and baseurl

2021-07-11T00:00:00-04:00

Jekyll’s site url and baseurl variables cause a lot of confusion for users. I see it all the time in the Jekyll Talk forum, Stackoverflow, or as bug reports in my themes.

My Jekyll site works locally but when I push it up to GitHub Pages it is broken with no styling and looks like this. Help!"

Improper use of Jekyll’s baseurl can break links to CSS, posts, and more as seen above.

What are `url` and `baseurl`?

So what exactly are the url and baseurl variables? To start, both are site-wide variables set in the _config.yml file and affect how Jekyll builds URLs. I like to describe them like this:

Site variable	Description
`url`	A site’s full URL including protocol, domain, and port (if applicable).
`baseurl`	Name of sub-directory the site is served from e.g., `/blog`.

How to use `url` and `baseurl`

A couple of important facts to keep in mind when using both:

Leave off trailing forward slashes when setting url

✅ Do this ❌ Don’t do this

website: https://mademistakes.com website: https://mademistakes.com/
baseurl is not needed for most sites and can be omitted.
baseurl is only necessary when hosting your site in a sub-directory. Project sites hosted on GitHub Pages are the common use-case of this variable.

✅ Do this	❌ Don’t do this
`website: https://mademistakes.com`	`website: https://mademistakes.com/`

Jekyll URL troubleshooting

If we go back to the example above with the broken CSS link and inspect the HTML’s source. You will often find that the link to the CSS file is incorrect for any number of reasons:

Double forward slashes e.g., //minima/assets/style.css
Missing base URL due to not using relative_url filter, absolute_url filter, or {{ site.baseurl }} in theme files.

When the path to the stylesheet is wrong the browser can’t load it. No stylesheet == plain looking website with no styles and looks broken.

Jekyll development and `site.url`

One other question I see asked over and over again from Jekyll users is:

Why are my links broken? They all start with http://localhost:4000 or http://127.0.0.1:4000.

This happens because in older versions of Jekyll (v3.3 through 4.1) it would reset site.url to localhost:4000 when JEKYLL_ENV=development (the default environment value), overriding whatever is set in the _config.yml. In newer versions of Jekyll (v4.2 and up) this reset of site.url no longer happens.

In older versions of Jekyll, site.url is also reset to http://localhost:4000 when spinning up a development server with the jekyll serve command.

`site.url` values

Jekyll version	Environment	CLI command	`site.url` value
4.2 (✨latest)	`development`	`serve`	value set in `_config.yml`
3.3	`development`	`serve`	reset to `http://localhost:4000`
4.2 (✨latest)	`development`	`build`	value set in `_config.yml`
3.3	`development`	`build`	value set in `_config.yml`
4.2 (✨latest)	`production`	`serve`	value set in `_config.yml`
3.3	`production`	`serve`	value set in `_config.yml`
4.2 (✨latest)	`production`	`build`	value set in `_config.yml`
3.3	`production`	`build`	value set in `_config.yml`

Under normal circumstances these two conditions won’t cause any headaches, especially when hosting on GitHub Pages as the environment and url are set automatically.

The issue surfaces when building locally, using an older versions of Jekyll, and then forgetting to set JEKYLL_ENV to production. Or pushing up files from a _site directory after running jekyll serve instead of jekyll build.

Examples

Below you will find examples of how to write different types of links that require site.url or site.baseurl values to work properly. Links marked as ✅ have valid URLs while those marked as ❌ are broken and will trigger a 404 file not found error.

Each of the examples assume:

Jekyll v4.2 or greater is installed.
The site is hosted on GitHub Pages in a sub-directory named blog.
Posts follow standard naming conventions of YYYY-MM-DD-filename.md inside of a _posts directory.
Image assets are in a images directory inside of the root.

Have the following _config.yml settings:

website: https://mmistakes.github.io
basewebsite: /blog
permalink: date

Markdown links

How to link to pages, posts, and images in Markdown.

Page in root directory

[about page](/about.html)

HTML output	-
`<a href="/about.html">about page</a>` URL is missing the base URL of `/blog` from the path.	❌

Page in sub-directory

[about page](/blog/about.html)
[about page]({{ site.baseurl }}/about.html)
[about page]({{ 'about.html' | relative_url }})

HTML output	-
`<a href="/blog/about.html">about page</a>`	✅

Page in date sub-directories

[Welcome to Jekyll post](/blog/2021/06/29/welcome-to-jekyll.html)
[Welcome to Jekyll post]({% post_url 2021-06-29-welcome-to-jekyll %})
[Welcome to Jekyll post]({% link _posts/2021-06-29-welcome-to-jekyll.md %})

HTML output	-
`<a href="/blog/2021/06/29/welcome-to-jekyll.html">Welcome to Jekyll post</a>`	✅

Image in root directory

[cheese pizza](pizza.jpg)

HTML output	-
`<img src="pizza.jpg" alt="cheese pizza">` URL is missing the base URL of `/blog` and sub-directory `/images` from the path.	❌

Image in sub-directory

[cheese pizza](images/pizza.jpg)

HTML output	-
`<img src="images/pizza.jpg" alt="cheese pizza">` URL is document-relative when it should be root-relative and is missing the base URL of `/blog` from the path.	❌

[cheese pizza](/images/pizza.jpg)

HTML output	-
`<img src="/images/pizza.jpg" alt="cheese pizza">` URL is missing the base URL of `/blog` from the path.	❌

[cheese pizza](/blog/images/pizza.jpg)
[cheese pizza]({{ '/images/pizza.jpg' | relative_url }})
[cheese pizza]({{ site.baseurl }}/images/pizza.jpg)

HTML output	-
`<img src="/blog/images/pizza.jpg" alt="cheese pizza">`	✅

Root-relative URL links

How to link resources with root-relative URLs, like stylesheets, favicons, and JavaScript.

<link rel="stylesheet" href="/assets/css/style.css">

HTML output	-
`<link rel="stylesheet" href="/assets/css/style.css">` URL is missing the base URL of `/blog` from the path.	❌

<link rel="stylesheet" href="/blog/assets/css/style.css">
<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/style.css">
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">

HTML output	-
`<link rel="stylesheet" href="/blog/assets/css/style.css">`	✅

Absolute URL links

How to link to resources that require the full URL, like a canonical URL in the page’s <head>.

<link rel="canonical" href="{{ page.url }}">

HTML output	-
`<link rel="canonical" href="/2021/06/29/welcome-to-jekyll.html">` URL is missing the site URL and base URL of `/blog` from the path.	❌

<link rel="canonical" href="{{ page.url | absolute_url }}">
<link rel="canonical" href="{{ page.url | prepend: site.baseurl | prepend: site.url }}">
<link rel="canonical" href="{{ site.url }}{{ site.baseurl }}{{ page.url }}">

HTML output	-
`<link rel="canonical" href="https://mmistakes.github.io/blog/2021/06/29/welcome-to-jekyll.html">`	✅

As you can see from above examples, Jekyll is flexible and allows for multiple ways of creating links. Personally I tend to lean on the relative_url and absolute_url filters as they require less typing and have some “smarts” to them.

The best option is the one that works for you!

Jekyll’s site.url and baseurl was originally published on Made Mistakes.

Not so quick with the Gatsby site optimizations

2021-06-22T16:14:38-04:00

This is the post where I talk about neglecting the site and pledge to blog more… wait, wasn’t I suppose to do this on January 1st?

Jokes aside, the last year and half I haven’t felt like writing. Between my “real” job, open source projects, COVID-19, buying and selling a house during a global pandemic, and moving the twins to a new school — where does someone find the time?

With life stabilized, I had time to dust the cobwebs off this site.

Build process

In the time that I ported over from Jekyll to Gatsby, GitHub released Actions to build, test, and deploy code. Migrating my build process over to GitHub Actions seemed obvious as I was hitting the limits of Travis CI’s free tier.

GitHub Actions migration

The process of updating involved creating a new YAML config file and adding environment variables. The cherry on top was leveraging an action to cache Gatsby’s .cache and public folders between builds.

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Caching Gatsby
 id: gatsby-cache-build
 uses: actions/cache@v2
 with:
 path: |
 public
 .cache
 key: ${{ runner.os }}-gatsby-build-${{ github.run_id }}
 restore-keys: |
 ${{ runner.os }}-gatsby-build-

Building the site from a cold start and no cache takes about 35 minutes to chug through 1,426 pages and resize/optimize 13,194 images. Each cached builds after takes ~1 minute to finish — that’s what I call an improvement!

 srcset="https://mademistakes.com/images/deploy-to-netlify-github-action_hu17888290899638654134.jpg 300w, https://mademistakes.com/images/deploy-to-netlify-github-action_hu8357628151382755290.jpg 620w"
>

Upgrade Gatsby to 3.x

Gatsby v3 added all sorts of improvements to the local development experience, which naturally I wanted to take part in. Unfortunately I had to wait for a few community plugins to be updated as the old Gatsby v2 versions broke my builds.

Plugin: gatsby-remark-source-name

Coming from Jekyll I’m used to organizing Markdown files into different collections like posts, pages, and comments. With Gatsby I place each in their own folder with a matching name in gatsby-config.js as shown below:

// excerpt from gatsby-config.js
plugins: [
 {
 resolve: 'gatsby-source-filesystem',
 options: {
 name: 'posts',
 path: `${__dirname}/src/posts`,
 },
 },
 {
 resolve: 'gatsby-source-filesystem',
 options: {
 name: 'pages',
 path: `${__dirname}/src/pages`,
 },
 },
 {
 resolve: 'gatsby-source-filesystem',
 options: {
 name: 'comments',
 path: `${__dirname}/src/comments`,
 },
 },
]

The gatsby-remark-source-name plugin then adds these as a sourceName field to Remark nodes. Allowing for an easy way to filter on collection type in my GraphQL queries:

# query for all "posts" Markdown files
return graphql(`
 {
 posts: allMarkdownRemark(
 filter: {
 fields: { sourceName: { eq: "posts" } }
 }
 ) {
 edges {
 node {
 html
 frontmatter {
 # Assumes you're using title in your frontmatter
 title
 }
 }
 }
 }
 }
`)

This broke with Gatsby v3 and threw the following error:

TypeError: Cannot destructure property 'createNodeField' of 'boundActionCreators' as it is undefined.

Turns out a plugin isn’t needed and you can achieve the same result by adding the following to gatsby-node.js.

exports.onCreateNode = ({ node, getNode, actions }) => {
 const { createNodeField } = actions
 if (node.internal.type === 'MarkdownRemark') {
 const fileNode = getNode(node.parent)
 createNodeField({
 node,
 name: 'sourceName',
 value: fileNode.sourceInstanceName,
 })
 }
}

Plugin: gatsby-source-github-api

Not sure why gatsby-source-github-api had problems with Gatsby 3.x, but this was the error message I encountered:

ERROR #11321 PLUGIN

"gatsby-source-github-api" threw an error while running the sourceNodes lifecycle:

Cannot destructure property 'createNode' of 'boundActionCreators' as it is undefined.

 8 | ) => {
 9 | console.log(boundActionCreators)
> 10 | const { createNode } = boundActionCreators;
 | ^
 11 | return new Promise((resolve, reject) => {
 12 | // we need a token to use this plugin
 13 | if (token === undefined) {

File: node_modules\gatsby-source-github-api\gatsby-node.js:10:11

A quick update of the npm package and all was well with the world.

Migrating Gatsby from v2 to v3

For everything that wasn’t related to outdated community plugins, I followed the official migration guide. A couple of find/replace commands across my project and I was done.

The other big change came from migrating gatsby-image to gatsby-plugin-image. This involved updating dependencies, fixing GraphQL queries, and replacing components.

Running npx gatsby-codemods gatsby-plugin-image did a lot of this work for me. Gatsby’s CLI tool is pretty good at letting you know if you’re using the deprecated gatsby-image component. It even let me know about instances where I should add alt attributes, which is good for accessibility.

Passing Core Web Vitals

 srcset="https://mademistakes.com/images/mm-lighthouse-scores-062021_hu13498284394947058712.jpg 300w, https://mademistakes.com/images/mm-lighthouse-scores-062021_hu1908794635994168237.jpg 620w"
>

Only took me a year of tinkering to get 100’s in Google Lighthouse for performance, accessibility, best practices, and SEO. Shipping less JavaScript by installing gatsby-plugin-preact certainly helped improve performance scores too.

But on some of my heavier pages with tons of DOM elements, 3rd party embeds from Twitter, and large animated GIFs — perf scores still take a hit.

Gatsby supports both WebP and AVIF image formats now, so I’ll need to experiment with those to see if I can shave even more time off. Just as long as my build times don’t increase too much…

Accessibility improvements

Adjusted the :focus and :hover styling of grid and list entries to render an outline around each when selected.
Bumped up the padding around footer links so they’re easier to tap.

Dark mode updates

Flipping between light and dark themes on the site worked before, but it had room to improve. For starters it wasn’t checking if a user had color theme preference (light or dark) set in their operating system.

To remedy this I installed gatsby-plugin-use-dark-mode to add a custom React Hook for use in my “dark mode toggle” component.

As an added benefit it also injects a small bit of JavaScript that helps with the dreaded flash of default theme plaguing sites with dark modes.

Table of contents updates

I’m still using a feature of Gatsby’s Markdown transformer to automatically create table of contents from headings. But instead of dropping it into a collapsible <details> element I styled the unordered list as a true sidebar.

Could just be me, but putting it off to the side has a nicer flow than before.

And because I can’t leave anything alone I started tinkering with the design of a few things.

Home page

Replaced the glitched image of me on the home page with a faux Polaroid frame and fixed it’s alignment with the rest of the page.

Archive pages

Changed the styling of the related tags component from a multi-column to an inline list to save space. I also reused this component on archive pages to help surface related topics that might have been buried before.

Added the featured posts component (used on the home page) to all archive pages… if applicable.

Works page

Pulled in more GitHub repositories under the Open source contributions section, added fork counts, and switched to a staggered card layout to add interest.

Speaking of open source, I switched this repository to private on GitHub. Way too many lazy developers were reusing my content with minimal changes. I have nothing against people forking my work and making it their own. But replacing my name and social media links with your own and calling it a day is weak.

I may make it public again if I have time to submodule out the content, but that might be too much pain for what it’s worth.

Experimenting with ads

To help offset the small costs of keeping this site up I’m experimenting with Google AdSense again. I was ready to ditch them once I saw how bad they degraded page speed performance.

After messing around with an intersection observer, I was able to keep things in check by waiting to load the Adsense scripts. I’m sure this JavaScript I added to Gatsby’s html.js file could be improved on. But for now it’s doing the trick and I’m pennies richer for it.

<script
 dangerouslySetInnerHTML={{
 __html: `
 (function(window, document) {
 function loadAds() {
 // Load Google AdSense
 var ad = document.createElement('script');
 ad.type = 'text/javascript';
 ad.async = true;
 ad.dataset.adClient = 'ca-pub-xxxxxxxxxxxxxxxx';
 ad.src = 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js';
 var sc = document.getElementsByTagName('script')[0];
 sc.parentNode.insertBefore(ad, sc);
 }

 var lazyLoad = false;
 function onLazyLoad() {
 if (lazyLoad === false) {
 lazyLoad = true;
 loadAds();
 console.log("advertisements loaded");
 }
 }

 if(!!window.IntersectionObserver){
 let observer = new IntersectionObserver((entries, observer) => {
 entries.forEach(entry => {
 if(entry.isIntersecting){
 onLazyLoad();
 observer.unobserve(entry.target);
 }
 });
 }, { rootMargin: "0px 0px 500px 0px" });
 document.querySelectorAll('.adsbygoogle').forEach(ad => { observer.observe(ad) });
 }
 })(window, document);
 `,
 }}
/>

Not so quick with the Gatsby site optimizations was originally published on Made Mistakes.

2 Little Rosebuds

2020-01-21T00:00:00-05:00

2 Little Rosebuds is a blog written by my wife Wendy Rose. The site started as a place for her to post about our twin girls and morphed into an outlet for her growing addiction to subscription boxes.

My responsibilities on the site include:

Wordpress installation and maintenance.
Creative, theme design, and development.
Content management.

Logo design

The 2 Little Rosebuds word mark has gone through several versions over the years. For this iteration I wanted something feminine — with subtle hints at veganism and “the twins,” to relate back to the blog’s identity and subject matter.

Style tiles

For all my projects I like to start with a quick sketch to help capture the overall tone and feel I’m going for. Creating a set of style tiles in Adobe Photoshop or Illustrator is my preferred way of doing that. Colors, basic typography, image treatments, and any other design elements I’m toying with all end up here.

Wordpress layouts

With over 3,500 posts in the last eight years, 2 Little Rosebuds has become an authority on all things “subscription box.” My main goals were to keep the experience familiar and to simplify the underlying code and design wherever possible.

This meant keeping the established color palette, but with minor adjustments to maintain adequate contrast for improved accessibility.

Reducing the amount of typefaces used to improve page loading speeds. And combining the masthead, navigation bar, and search form into a single organism to give space back to what’s important — post content.

srcset="https://mademistakes.com/images/2lrb-post-layout_hu9383348575185666775.jpg 300w, https://mademistakes.com/images/2lrb-post-layout_hu16998727187537031759.jpg 620w" ></p>

Single post layout.

Post content is given prominence by using a centered single column layout to make reading comfortable. Just Wendy’s words and photographs — no side bar clutter or distracting advertisements.

srcset="https://mademistakes.com/images/2lrb-category-archive-layout_hu8164571630906025463.jpg 300w, https://mademistakes.com/images/2lrb-category-archive-layout_hu8255706024119937359.jpg 620w" ></p>

Category archive layout.

Layouts used for the directory got a refresher to better showcase the 650 subscription boxes listed within. Search, sort controls, box type refinements, and review scores are placed in familiar locations to help discover subscriptions while browsing.

srcset="https://mademistakes.com/images/2lrb-subscription-box-directory_hu221677947028435887.jpg 300w, https://mademistakes.com/images/2lrb-subscription-box-directory_hu4241703625271259545.jpg 620w" ></p>

Subscription box directory layout.

srcset="https://mademistakes.com/images/2lrb-subscription-box-layout_hu15658623637715645819.jpg 300w, https://mademistakes.com/images/2lrb-subscription-box-layout_hu17569311635511069824.jpg 620w" ></p>

Subscription box detail page layout.

2 Little Rosebuds was originally published on Made Mistakes.

Twenty Nineteen

2020-01-01T00:00:00-05:00

First time doing a year in review post thingy. The statistics below are just for fun as there’s nothing to compare them against yet. Should be interesting to see how they deviate next year as I would have never guessed some would be as high as they were.

2019 by the numbers

1 blog post
4 side projects
365 days spent growing a beard
33 video games played
64 movies watched
56 days closing all rings on Apple Watch
6,522 steps/day average

Web development

Starting way back in 2017 I experimented with migrating my Jekyll built personal site over to Gatsby… things didn’t work out so well. It took until 2019 for Gatsby and its ecosystem to mature enough for me to take it seriously.

Up until then it couldn’t handle building my site of ~1,000 posts, paginated category/tag archives, and 13,000 images. Plagued with FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory messages I waited as Gatsby received performance optimizations that fixed my build woes.

With the right cocktail of plugins I finally launched a Gatsby powered site on the last day of 2019, December 31st. Expect a post mortem in a future article as there was a lot I struggled with:

Adapting Liquid templates to vanilla JavaScript and React.
Finding Markdown parity with Kramdown features.
Deploying my own instance of Staticman and getting comments working with Gatsby.
Replacing custom Jekyll plugin tags.
Working through Lighthouse scores that were often worse than the pre-Gatsby site.
Build timeouts on Netlify.

Open source contributions

In 2019 I pushed 1,056 commits to GitHub, most of which were to my three most popular Jekyll themes: Minimal Mistakes, So Simple, and Basically Basic.

It boggles my mind that a repository that started out as a stripped down theme of my personal site has been: downloaded 96,901 times, forked 10,100 times, and starred 5,993 times. Thanks to everyone who has supported its continued development with kind words and donations!

A yeard and a half

I’ve had a love/hate relationship with beard growing for as long as I can remember. For whatever stupid reason I decided I wanted to grow a yeard in 2018… during the middle of the summer.

Beard progression at 3 months, 6 months, and 12 months.

At the close of 2019 I’ve gone eighteen months without shaving and plan on trying for whatever you call a 2x yeard. We’ll see though as eating soup, snagging hairs in zippers, and daily beard maintenance does get old on occassion.

Video games played

If it wasn’t for the Nintendo Switch and being a portable console, I would have never played this many games. Being able to quickly resume a game before dinner or when the twins are in bed makes a difference.

This game is ridic.#UntitledGooseGame #NintendoSwitch pic.twitter.com/0YHhFVmrpU
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) September 21, 2019

I’m slowly making it through my backlog of Playstation must plays, but sneaking those in has been difficult. As most have mature ratings, they’re not something I can play with my kids. And the fact that it’s not a portable console means I need to wrestle the television from my wife, who sure as shit doesn’t want to watch me game for an hour.

Game	Rating	Note
Sayonara Wild Hearts (Switch)	★★★★	Not quite as rhythm heavy as I was expecting, but solid.
Untitled Goose Game (Switch)	★★★★★	A game I never knew I wanted till I did.
Beyond Two Souls (PS4)	★★★	About 2 hours in, I’m a sucker for David Cage games.
Blasphemous (Switch)	★★★	Started the demo, will revist later.
River City Girls (Switch)	★★★★	Music, art, brawling is all great. Has me pumped for Streets of Rage 4.
Luigi’s Mansion 3 (Switch)	★★★	Controls take some getting used to. CO-OP is fun once you unlock Gooigi. Challenging boss battles.
Detroit: Become Human (PS4)	★★★★	Would like to replay to see all missed story paths… if I ever have the time.
Super Mario Maker 2 (Switch)	★★★★★	Consumer of Mario levels more so than a creator. Suffered through online lag to hit Rank A in multiplayer.
Uncharted: The Lost Legacy (PS4)	★★★★	Completed the story.
The Legend of Zelda: A Link to the Past (Switch SNES)	★★★★★	Playing through for the first time on an actual console. At the last dungeon, ready to fight Ganon.
Super Mario World (Switch SNES)	★★★★★	Mario Maker 2 got me revisiting the classics.
Ninja Gaiden (Switch NES)	★★★★★	How I ever beat this as a kid is beyond me.
Zelda II: The Adventure of Linke Switch (NES)	★★★★	That last palace is a doozy…
Uncharted 4: A Thief’s End (PS4)	★★★★★	Completed the story, missed a bunch of collectibles.
Uncharted The Nathan Drake Collection (PS4)	★★★	Rushed my way through 1, 2, and 3 so I could start 4.
New Super Mario Bros. U Deluxe (Switch)	★★★★	I’m cool with Nintendo re-releasing Wii U games I never played.
Cuphead (Switch)	★★★★	20% complete. This game isn’t fooling around.
Sonic Mania (Xbox One)	★★★★	Fits in perfectly with the Sega Genesis era of games. Challenge ramps up at the end.
Super Kirby Clash (Switch)	★★	Micro-transaction hell.
Super Phantom Cat: Remake (Switch)	★★★	Purchased on the cheap, OK platformer.
Yoshi’s Crafted World (Switch)	★★★★	Great art direction. CO-OP’d with the twins.
Super Mario Party (Switch)	★★★	Great amount of mini-games but really wish it would let you use Pro Controllers.
Super Mario Odyssey (Switch)	★★★★★	Completed the story and bought most costumes. Collected 596 moons.
Tetris 99 (Switch)	★★★★	Love me some Tetris. Won 2 of 388 games.
Thumper (Switch)	★★★★	So much dread.
Gris (Switch)	★★★★	Walking simulator with a watercolor aesthetic.
Hollow Knight (Switch)	★★★★	Sank over 20 hours into it and no idea if I’m near the end or not.
What Remains of Edith Finch (PS4)	★★★★	Surprisingly good Playstation Plus free game.
Hellblade: Senua’s Sacrifice (PS4)	★★★★★	Loved everything about this game. Can’t wait for the sequel.
Bulletstorm: Full Clip Edition (PS4)	★★★	Picked up for free via Playstation Plus, about 75% the way through. Potty mouth shooter fare.
The Last Guardian	★★	Really wanted to like this one, but the floaty ass controls ruins it for me. Made it about midway through the story… I think.
Shadow of the Tomb Raider (PS4)	★★★★	Enjoyed the tropical scenery more than the snow in Rise.
The Order: 1886 (PS4)	★★★★	Purchased on sale, not bad.
Super Smash Bros. Ultimate (Switch)	★★★	Awful at fighting games. Unlocked all the characters, stopped playing shortly after.

Movies watched

According to Letterboxd below are all the flicks I watched last year. And here I thought I binged more television series than movies — guess not.

Movie	Rating	Note
Star Wars: The Rise of Skywalker (2019)	★★★	Should have been split into two parts.
Mission: Impossible - Fallout (2018)	★★★	By the Numbers.
Marriage Story (2019)	★★★	Meh.
Frozen 2 (2019)	★★★	Too much singing.
The Grinch (2018)	★★★	Didn’t bore me as much as the Jim Carrey version.
Klaus (2019)	★★★	For the kids… and it’s the Christmas season right?
The Irishman (2019)	★★★	The digital de-aging didn’t bother me.
The Game Changers (2018)	★★★	Tough vegans.
The Lobster (2015)	★★★	I have questions.
Carrie (1976)	★★★	So that’s where all the references came from.
Tell Me Who I Am (2019)	★★★★	I’m a sucker for documentaries of this nature.
El Camino: A Breaking Bad Movie (2019)	★★★	Unnecessary but good.
Skin (2018)	★★★★	If it has a hint of a true story to it, I’ll bite.
Between Two Ferns: The Movie (2019)	★★★★	Yup, what I expected.
In the Shadow of the Moon (2019)	★★★	Sort of like Looper I guess.
Pulp Fiction (1994)	★★★★★	Rewatched.
Don’t Break Down: A Film About Jawbreaker (2017)	★★★★	Probably need to enjoy their music to get something out of this.
Screwball (2018)	★★★	Roids.
Ralph Breaks the Internet (2018)	★★★	A few memes a lot of zzzZzzs.
Jack of all Trades (2018)	★★★	Hard toilet paper.
Pokémon Detective Pikachu (2019)	★★	I call bullshit.
Bob Lazar: Area 51 and Flying Saucers (2018)	★★	Zzzzzz.
Being Frank: The Chris Sievey Story (2018)	★★★	The true story behind that one Michael Fassbender flick.
Toy Story 4 (2019)	★★★	Spoony.
Us (2019)	★★★	I have questions.
Avengers: Endgame (2019)	★★★	Ten years of plot threads tied up in 3 hours… exactly how you’d expect.
The Transformers: The Movie (1986)	★★★★★	Rewatched with commentary. Not much value added from the director who explained exactly what we saw on screen. More insight from the writer would have been better.
Extremely Wicked, Shockingly Evil and Vile (2019)	★★★	Found the tapes documentary more interesting.
The Billboard Boys (2016)	★★★	…took a shower, ready to go another two years.
Mids 90s (2018)	★★★	Didn’t disappoint with the non-ending.
Zodiac (2007)	★★★	Rewatched.
Glass (2019)	★★★	Of course it was a purple iMac.
Christopher Robin (2018)	★★★	Meh.
This is 40 (2012)	★★★★	Relatable.
The Endless (2017)	★★★	Groundhog day for hipsters.
The Stanford Prison Experiment (2015)	★★★	So many bad fake mustaches.
The Fear of 13 (2015)	★★★	Prison.
Kong: Skull Island (2017)	★★★	Dong.
Aquaman (2018)	★★★★	We could have just peed on it.
Creed II (2018)	★★★	Nostalgic for Rocky IV.
The Hateful Eight (2015)	★★★	Mmm, jelly beans.
Triple Frontier (2019)	★★★	Kept waiting for the other shoe to drop, then Metallica did.
The Matrix Revolutions (2003)	★★★	Rewatched.
The Matrix Reloaded (2003)	★★★	Rewatched.
Eighth Grade (2018)	★★★	Just wait until high school.
The Matrix (1999)	★★★★	Rewatched.
The Lost Arcade (2015)	★★★	Fighting game snobbery.
Free Solo (2018)	★★★★	“So delighted.”
Mandy (2018)	★★★	There’s no arguing this thing oozed style. Not sure what the fuck I just dreamed though.
Lords of Chaos (2018)	★★★	Strangely enough, black metal and Sigur Rós compliment each other well.
Paddleton (2019)	★★★	Slow burn.
Shirkers (2018)	★★	This score really annoyed the piss outta me.
Isle of Dogs (2018)	★★★	Yup, it’s a W.A. film.
Alt-Right: Age of Rage (2018)	★★★
The Edge of Seventeen (2016)	★★★	I feel like I’ve seen this movie before…
Abducted in Plain Sight (2017)	★★★★	Wow
Root Cause (2019)	★★★	No comment.
The Family I Had (2017)	★★★
Toy Story 2 (1999)	★★★	Rewatched.
Toy Story (1995)	★★★	Rewatched.
Fyre (2019)	★★★	Living the dream.
Unbreakable (2000)	★★★★	Rewatched.
A Fat Wreck (2016)	★★★★	Nostalgic for pop punk.
Solo: A Star Wars Story (2018)	★★★★	Can’t believe all the negative press.
Black Mirror: Bandersnatch (2018)	★★★	Would have been fine with this not being interactive at all.

Health and activity

The last couple of years I’ve been wanting to ditch FitBit devices for Apple Watch. My hestitation being battery life and needing to charge it daily. As someone who wore a Fitbit for 5 days straight without charging — this was a deal breaker.

When Apple released a Watch this fall with an always-on screen, I decided to try it out. On paper it does pretty much everything the Fitbits I’ve owned for years do. But some reason it’s motivated me to be active in ways they couldn’t.

iOS health app screenshots for 2019.

I’ve gone from hitting move and workout goals 3 days a week to all 7. Earning gift card rewards via Aetna’s Attain app is a great motivator as well.

I still don’t like that I need to charge it everyday since I use it for sleep tracking. But a well timed charge during my morning shower is usually enough to top it off for the day.

Heading into 2020

I don’t consciously set goals or make resolutions really. If I can do more of the same as 2019 I’ll be happy. Now that I’m more active, I’d like to amp up my consumption of fruits and vegetables this year. I eat a lot of beige processed food that I’m sure is up to no good in my body.

We’ll see I guess…

Twenty Nineteen was originally published on Made Mistakes.

Faster Netlify builds

2019-02-26T00:00:00-05:00

Slowly but surely, I’ve been chipping away at my site’s build time on Netlify.

There’s little left for me to optimize until Jekyll drops some nice updates in version 4.0. I’ve cached the rendering of Liquid includes across _layouts via the {% include_cached %} tag, limited use of {% for %} loops over large collections like {% site.posts %}, and stripped Jekyll’s duties down to solely a HTML generator.

The “little” that remains, is about a gigabyte of images I pipe through Gulp. Thousands of high resolution images are processed by Sharp into various sizes. I’ve been able to knock this down from 18 minutes, to six on a fresh build…

 srcset="https://mademistakes.com/images/netlify-deploy-log_hu14507604561895696040.png 300w, https://mademistakes.com/images/netlify-deploy-log_hu12734368324671917220.png 620w"
>

When building the site locally I store the image artifacts in a temporary folder, and generate new ones if the source changes. When Netlify generates the site it processes these images each build — regardless if they have changed or not.

By stashing the processed images in a secret Netlify cache folder¹ and using Gulp to move files around, I cut the build time in half. Which is fantastic since I’m now averaging 5–8 minutes for dependencies to install, Jekyll to run, and Netlify to deploy the site.

Excerpt from my Gulp build task

// 'gulp copy:images:cached' -- copies cached images from Netlify's `/opt/build/cache/` folder to `/dist/`

gulp.task("copy:images:cached", () => {
 return gulp
 .src(paths.imageFilesCachePath + "/**/*")
 .pipe(newer(paths.imageFilesSite))
 .pipe(gulp.dest(paths.imageFilesSite));
});

Netlify has an undocumented /opt/build/cache/ folder that is cached and persists between builds. Faster static site builds Part 1 ↩︎

Faster Netlify builds was originally published on Made Mistakes.

Autumn refresh

2018-11-12T00:00:00-05:00

Lately I’ve been toying with the idea of migrating from Jekyll to GatsbyJS (more on that in a future post). Initial tests look promising, but there are some issues I’m still working through.

In the meantime I’ve taken visual cues from React components I built in a repo where I was playing around with Gatsby, and adapted them here as standard HTML/CSS.

Design changes

In Made Mistakes v12 text and image where large and readible, but didn’t exactly fill the canvas elegantly. I wanted to change that with this design refresh.

srcset="https://mademistakes.com/images/mm-desktop-design-old_hu10846213963406749627.jpg 300w, https://mademistakes.com/images/mm-desktop-design-old_hu8043782310772017601.jpg 620w" ></p>

Site design before the refresh.

Since majority of the visitors to my site use modern browsers, I had a good excuse to play with display: grid. I’ve removed the Susy mixins and most of the float based columns, which cut the amount of CSS I had to write considerably.

srcset="https://mademistakes.com/images/mm-desktop-design-new_hu131218572327163915.jpg 300w, https://mademistakes.com/images/mm-desktop-design-new_hu9270831330690345807.jpg 620w" ></p>

Site design after the refresh.

To my eye this new layout breaks up the page better. Content comes into view earlier on the page, and there’s plenty of room for ancillary information on the right. With a little position: sticky sprinkled on the aside column, internal skip links stay fixed in view — when space allows.

Accessibility improvements

This refresh prompted me to test how accessible the site is and fix any glaring issues.

Buttons have an accessible name

When a button doesn’t have an accessible name, screen readers announce it as “button”, making it unusable for users who rely on screen readers.

Digging in, I discovered bigfoot.js¹ didn’t name <button> elements that it created. Thankfully the button markup is configurable so I was able replace a set of presentational-only <svg> elements with unique names instead.

var bigfoot = $.bigfoot({
 actionOriginalFN: 'delete',
 buttonMarkup: (
 '<div class="bigfoot-footnote__container">' +
 ' <button href="#" class="bigfoot-footnote__button" rel="footnote"' +
 ' id="{{SUP:data-footnote-backlink-ref}}"' +
 ' data-footnote-number="{{FOOTNOTENUM}}"' +
 ' data-footnote-identifier="{{FOOTNOTEID}}"' +
 ' alt="See Footnote {{FOOTNOTENUM}}"' +
 ' data-bigfoot-footnote="{{FOOTNOTECONTENT}}">' +
 ' <span class="visually-hidden">{{FOOTNOTENUM}}</span>' +
 ' </button>' +
 '</div>'
 )
});

Color contrast is satisfactory

The color of elements like captions and footer text were too light, so I darkened them. I did the same for links by giving them a contrast ratio of 4.77.

The Color Picker in Chrome’s DevTools will show you the contrast ratio of text elements to help make your site more accessible to users with low-vision impairments or color-vision deficiencies.

Performance improvements

Optimizations with the biggest impact (minifying, concatenating, inlining critical CSS) I was already doing, but there was still room for improvement.

Defer offscreen images

Consider lazy-loading offscreen and hidden images after all critical resources have finished loading to lower time to interactive.

Large feature images were already lazy-loaded and served responsively using srcset and a handful of sized images. Images found in the body {{ content }} of my Markdown files were not.

Taking a cue from gatsby-remark-images’ playbook, I wrote a small plugin to convert Markdown image syntax into an <img> element with synatactically sugar for lazy-loading. To my surprise this actually worked.

# Description: Jekyll plugin to replace Markdown image syntax with lazy-load HTML markup

Jekyll::Hooks.register :posts, :pre_render do |post, payload|
 docExt = post.extname.tr('.', '')
 # only process Markdown files
 if payload['site']['markdown_ext'].include? docExt
 newContent = post.content.gsub(/(?:!\[(.*?)\]\((.*?)\))/, '<noscript><img src="\2"></noscript><img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" data-src="\2" alt="\1" class="lazyload fade-in">')
 post.content = newContent
 end
end

Avoids an excessive DOM size

Browser engineers recommend pages contain fewer than ~1,500 DOM nodes. The sweet spot is a tree depth < 32 elements and fewer than 60 children/parent element. A large DOM can increase memory usage, cause longer style calculations, and produce costly layout reflows.

Trimming <div> fat where I could helped cut page weight down. Some hefty pages remain (I’m looking at your PaperFaces gallery, but most fall under the 1,500 DOM node threshold. In the future I hope to fix this issue with a gallery pagination component when switching to Gatsby.

Lighthouse audits comparison

Lighthouse audit results before optimizations.

Lighthouse audit results after optimizations.

Not sure why metrics like Speed Index increased. But Time to Interactive, First Meaningful Paint, and First CPI Idle all show improvements, so I guess that’s why the site went from a 79 in performance, to an 89.

Build and deploy

And if all of this wasn’t enough, I also made the switch away from Travis CI, to Netlify. Instead of a 48 line .travis.yml file I now have a three line netlify.toml.

The Netlify builds are about 2-4 minutes faster than those with Travis CI. And look to be even quicker if I leverage undocumented Netlify cache folders that persists between builds. Using these to store the thousands of images I pipe through resizing tasks could shave another 6-8 minutes off my build.

A jQuery plugin used to make footnotes less visually distracting. ↩︎

Autumn refresh was originally published on Made Mistakes.

Water tension

2018-06-04T00:00:00-04:00

Portrait of Marie M. inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9″ iPad Pro.

Approximately 6 hours of work spread across a couple of weeks.

~6 hours of work spread across a couple of weeks, because who has time? pic.twitter.com/faECZVYPSP
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) June 3, 2018

Tools used:

Water tension was originally published on Made Mistakes.

The two hour beard

2018-04-30T00:00:00-04:00

Portrait of Ale B. inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9" iPad Pro.

Two hours and 30 minutes of beard scribbling over the last couple of weeks. Because who has time to relax draw in a single sitting?

Time-lapse export video via #Procreate #WIP #Sktchy pic.twitter.com/uqMtzknWYp
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) April 30, 2018

Tools used:

The two hour beard was originally published on Made Mistakes.

Turn away

2018-04-14T00:00:00-04:00

Portrait of Tatha S. inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9″ iPad Pro.

Using Apple Pencil to lay lines.

Procreate time-lapse export pic.twitter.com/Xw5ozxENYI
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) April 12, 2018

Tools used:

Turn away was originally published on Made Mistakes.

Corpse paint your tears

2018-04-03T00:00:00-04:00

Portrait of Maya Z. inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9″ iPad Pro.

Slowly building up tones.

#Procreate time-lapse export pic.twitter.com/dSNE7fKHWb
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) March 31, 2018

Tools used:

Corpse paint your tears was originally published on Made Mistakes.

Glowing pencil practice

2018-04-03T00:00:00-04:00

Portrait of Foggy 365 inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9″ iPad Pro.

Trying to emulate the look of graphite on paper…

Time-lapse replay exported from @Procreate pic.twitter.com/Ww2m40qdoI
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) March 24, 2018

Tools used:

Glowing pencil practice was originally published on Made Mistakes.

Back at it

2018-03-22T00:00:00-04:00

Portrait of Marion K. inspired by a photograph on Sktchy. Digitally painted with Procreate on a 12.9″ iPad Pro.

I finally got my hands on a new iPad Pro and the highly responsive Apple Pencil. This is the stylus I have been waiting for!

Process video pic.twitter.com/MfP9TmESlR
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) March 22, 2018

Tools used:

Back at it was originally published on Made Mistakes.

Choke’s embrace

2017-08-31T00:00:00-04:00

Portrait of Lunar Ashes inspired by a photograph on Sktchy. Digitally painted with Procreate on an iPad Air 2.

A lovers embrace painting for a Valentine’s Day inspired Sktchy challenge titled #WAXcupid.

Stupid unresponsive stylus. Need a Pro + Pencil already 😭 pic.twitter.com/95x5rXVsyr
— 𝔐𝔦𝔠𝔥𝔞𝔢𝔩 ℜ𝔬𝔰𝔢 (@mmistakes) February 19, 2017

Tools used:

Choke's embrace was originally published on Made Mistakes.

Optimizing and automating my Jekyll site build

2017-08-30T00:00:00-04:00

Not going to lie — I love Jekyll, but huge static sites like mine take forever to build. What used to take seconds now go on for over 30 minutes, as thousands of files are generated and optimized.

Inspired by Anne Tomasevich’s post, Optimizing Jekyll Performance with Gulp — I begun digging into my build process to identify performance bottlenecks.

At the time of writing this post, my site contained roughly:

1,028 images generated at different sizes (5,140 in total).
1,052 total documents (991 posts / 14 pages / 3 sets of collections).
535 comments stored as YAML data files.

And was built with the following Jekyll plugins: jekyll-picture-tag, sort_name, jekyll-archives, jekyll-assets, jekyll/tagging, jekyll-tagging-related_posts, jekyll-sitemap, jemoji, and jekyll-typogrify.

Using Jekyll’s profiler flag --profile, I measured how long the following tasks took to complete¹. Before each build I ran jekyll clean to wipe _site, .asset-cache and any other temporary files to keep results more consistent.

Task description	Windows	Mac
Generate responsively sized `page.image.feature` images	1288.29s	1429.26s
Minify HTML with `layout: compress`	39.35s	11.18s
Read `/images/` and copy to `_site/`	32.39s	23.63s
Build tag pages with jekyll-archives	17.40s	9.99s
Build tag index page with `sort_tag` filter	2.62s	0.59s
List related posts with jekyll-tagging-related_posts, jekyll/tagging, and `LSI: true`	38.36s	17.87s
List related posts with vanilla `related_posts`	1.65s	4.90s
Preprocess, concatenate, minify, and cache bust SCSS and JS with jekyll-assets	78.75s	25.03s
Display masthead and overlay menu from `_data`	9.66s	7.82s
List post comments from `_data`	7.10s	2.22s
Display colophon from `_data`	0.20s	0.49s
List post taxonomy metadata	3.48s	1.18s
List post breadcrumb links	2.83s	1.03s
List featured posts	0.20s	0.44s
Build style guide collection	1.16s	0.31s
List post social sharing links	5.09s	0.97s

Is Jekyll faster on macOs or Windows?

For giggles I also tested my Windows and Mac development environments against each other. While not exactly an apples to apples comparison I thought it would be interesting to note any variations.

Windows Environment	Mac Environment
Lenovo ThinkStation E30	iMac 21.5-inch, Late 2013
Processor 3.30 GHz Intel Xeon E31245	Processor 2.7 GHz Intel Core i5
Memory 16 GB	Memory 16 GB 1600 MHz DDR3
Intel SSDSA2BW160G3L 137GB	1.12 TB Fusion Drive
Windows 7 Professional Service Pack 1	OS X El Capitan 10.11.6
ruby 2.2.4p230 [x64-mingw32]	ruby 2.1.0p0 (2013-12-25 revision 44422) [x86_64-darwin12.0]

Optimization

The numbers above don’t lie. Relying on Jekyll and friends to do jobs more suited for a task runner like Gulp was slowing the build. Armed with this knowledge I started stripping down Jekyll to one of its core purposes — converting Markdown files into HTML.

Doing this also allowed me to make my site’s content more portable and not as reliant on a specific static-site generator. In the off-chance I wanted to swap Jekyll for another SSG like Hugo or Gatsby, I could.

CSS and JavaScript assets

Jekyll Assets is a great plugin that served me well for a long time by: preprocessing, vendor prefixing, concatenating, minifying, and fingerprinting assets. But with a site of my size it was painfully slow to iterate with during front-end development.

Making a change to a Sass partial would trigger a full site rebuild, which meant waiting a few minutes before it could be previewed in a browser. Jekyll’s incremental build feature might have helped here, but I never had much luck getting it to work reliably.

During development CSS or JavaScript changes would ideally be pushed instantly to the browser with something like Browsersync. By replacing Jekyll Assets with the following Gulp alternatives I was able to do this, and improve build times by 93%:

node-sass and gulp-sass: natively compile SCSS files to CSS.
gulp-autoprefixer: vendor prefix CSS.
gulp-cssnano: minify CSS.
gulp-concat: concatenate JavaScript.
gulp-uglify: minify JavaScript with UglifyJS.
gulp-sourcemaps: add source maps for CSS and JS.
gulp-gzip: gzip CSS and JS.
gulp-rev: append hash to CSS and JS filenames for cache busting.

Task description	Jekyll Assets	Gulp
CSS and JavaScript asset pipeline	25.031s	1.577s

Here’s a small taste of the Gulp file I’m using for the site’s styles if you’re curious:

// 'gulp styles' -- creates a CSS file from SCSS, adds prefixes and creates a Sourcemap
// 'gulp styles --prod' -- creates a CSS file from your SCSS, adds prefixes,
// minifies, and cache busts it (does not create a Sourcemap)
gulp.task('styles', () => {
 return gulp.src([paths.sassFiles + '/main.scss'])
 .pipe(when(!argv.prod, sourcemaps.init()))
 // preprocess Sass
 .pipe(sass({precision: 10}).on('error', sass.logError))
 .pipe(postcss([
 // add vendor prefixes
 autoprefixer({
 browsers: [
 'last 2 versions',
 '> 5%',
 'IE 9'
 ]
 })
 ]))
 // minify for production
 .pipe(when(argv.prod, when('*.css', cssnano({autoprefixer: false}))))
 .pipe(size({showFiles: true}))
 // output sourcemap for development
 .pipe(when(!argv.prod, sourcemaps.write('.')))
 .pipe(when(argv.prod, gulp.dest(paths.sassFilesTemp)))
 // hash CSS for production
 .pipe(when(argv.prod, rev()))
 .pipe(when(argv.prod, size({showFiles: true})))
 // output hashed files
 .pipe(gulp.dest(paths.sassFilesTemp))
 // generate manifest of hashed CSS files
 .pipe(rev.manifest('css-manifest.json'))
 .pipe(gulp.dest(paths.tempDir + paths.sourceDir + paths.dataFolderName))
 .pipe(when(argv.prod, size({showFiles: true})))
 .pipe(when(!argv.prod, browserSync.stream()))
});

// function to properly reload your browser
function reload(done) {
 browserSync.reload();
 done();
}

// 'gulp serve' -- open site in browser and watch for changes
// in source files and update them when needed
gulp.task('serve', (done) => {
 browserSync.init({
 // tunnel: true,
 // open: false,
 port: 4000, // change port to match default Jekyll
 ui: {
 port: 4001
 },
 server: [paths.tempFolderName, paths.siteFolderName]
 });
 done();

 // watch various files for changes
 gulp.watch(paths.sassFilesGlob, gulp.series('styles', reload));
});

Without going too deep into how these Gulp tasks work, the gist is:

A glob of files have “stuff” done to them using various plugins.
These files are placed in a temporary folder excluded from Jekyll so they don’t trigger a full site rebuild during development.
Production builds move these temporary files and deploys them alongside the HTML files generated by Jekyll.

Image assets

Resizing a thousand or so images to serve them responsively is no joke — taking over 20 minutes to complete in my site’s case. Up until now I was using the Jekyll Picture Tag plugin to do this work for me… which wasn’t ideal.

To try and see if Node and Gulp could do this faster I came up with a set of Gulp tasks to:

Generate thousands of “feature” images² at 4 different sizes with gulp-responsive.
Optimize all images using gulp-imagemin.
Save the optimized images directly to the destination folder — bypassing Jekyll and a full-site rebuild.

This helped some, but it wasn’t until I dropped GraphicsMagick for Sharp³ did I see a noticeable improvement…

Sharp really is as fast as they say

I shaved 18 minutes off my build time using this high speed Node.js module!

Task description	Graphics Magick	Sharp
Resize and optimize 1,014 source images into 5 target sizes	1288.29s	171.00s

The other missing piece was generating the necessary markup for responsive images⁴. Because I was no longer using the {% picture %} tag to output a fully formed <picture> element, I had to roll my own responsive image markup.

{% if page.image.feature %}
 {% assign f = page.image.feature | split: '.' %}
 <img src="{{ f[0] | relative_url }}-320.{{ f[1] }}"
 srcset="{{ f[0] | relative_url }}-768.{{ f[1] }} 768w,
 {{ f[0] | relative_url }}-1024.{{ f[1] }} 1024w,
 {{ f[0] | relative_url }}.{{ f[1] }} 1920w"
 alt="{{ page.title }}">
{% endif %}

This bit of Liquid takes the filename as defined by page.image.feature, splits it at the extension, appends suffixes that match those used in the gulp-responsive task, and adds them to the srcset attribute. Boom, resolution switching images!

Simplify layouts

With the bulk of the time savings coming from faster image resizing tasks, I went after some low-hanging fruit next by decluttering my layouts. Anything that detracted from the main content or added visual noise to the page was fair game for removal.

Including buttons at the bottom (or top of post) didn’t really boost shares of my content on Twitter or Facebook — so I dropped them. If someone wants to share it on social media they’ll use the builtin methods of iOS/Android or do it the old fashioned way of copy-pasting a URL.

Replace `layout: compress`

Occasionally things on the site would break if inline JavaScript with // styled comments were used. This happened because of a complex set of Liquid filters used in my compress layout to reduce whitespace in the generated HTML.

The fix was easy, just surround inline JavaScript comments with /* */ instead. Or do what I did, stop using layout: compress and minify with these Gulp plugins instead: gulp-htmlmin and gulp-gzip.

// 'gulp html' -- does nothing
// 'gulp html --prod' -- minifies and gzips HTML files for production
gulp.task('html', () => {
 return gulp.src(paths.siteFolderName + paths.htmlPattern)
 .pipe(when(argv.prod, htmlmin({
 removeComments: true,
 collapseWhitespace: true,
 collapseBooleanAttributes: false,
 removeAttributeQuotes: false,
 removeRedundantAttributes: false,
 minifyJS: true,
 minifyCSS: true
 })))
 .pipe(when(argv.prod, size({title: 'optimized HTML'})))
 .pipe(when(argv.prod, gulp.dest(paths.siteFolderName)))
 .pipe(when(argv.prod, gzip({append: true})))
 .pipe(when(argv.prod, size({
 title: 'gzipped HTML',
 gzip: true
 })))
 .pipe(when(argv.prod, gulp.dest(paths.siteFolderName)))
});

Minifying HTML with Gulp

In my tests, replacing _layouts/compress.html with Gulp tasks to minify and gzip every HTML file ended up being slightly slower.

Task description	compress layout	gulp-html and gulp-gzip
Minify HTML files	39.348s	47.00s

I’m willing to live with the extra 8 seconds of build time as it helps avoid potential site breakages due to badly minified scripts…

Reduce and replace JavaScript

I’m close to ditching jQuery and going vanilla, but I’m not quite there yet. Where possible I’ve ditched jQuery plugins and replaced with “lighter” alternatives. Here’s a few highlights:

Replaced Magnific Popup with Lity.
Replaced Lazyload with Lazysizes + Lazysizes responsive images polyfill extension.
Added SVG 4 Everybody for external SVG spritemap support.
Replaced FitVids.JS with responsive embed CSS and a custom Jekyll video embed tag.

Results

Decoupling the asset pipeline from Jekyll and Gulp-ifying it made the biggest splash in terms of build time. Along with Browsersync, any asset (CSS, JavaScript, images and icons) updates could be previewed almost instantly. Greatly speeding up the time it takes to develop and iterate the site’s front-end.

Automation & Continuous Integration

After ditching Disqus last year to roll my own static-based solution powered by Staticman, I needed to find a better way of deploying the site. Merging in new comments, pulling those commits down, manually building the site locally, and then deploying to my web server wasn’t ideal.

With some research I determined a continuous integration⁵ platform like Travis CI⁶ that integrates with GitHub was what I needed.

 srcset="https://mademistakes.com/images/mm-travis-ci-screenshot_hu10714485042521995175.png 300w, https://mademistakes.com/images/mm-travis-ci-screenshot_hu9072102099428930831.png 620w"
>

Setting things up with Travis CI wasn’t too painful, but there was some trial and error getting dependencies squared away. I’d suggest reading through their documentation, but the basic idea is:

Sign in to Travis CI with your GitHub account and grant it access.
Configure the build and deployment scripts with a .travis.yml file.
Set the type of triggers⁷ that initiate a build.

Travis CI configuration

Let’s take a closer look my .travis.yml config file and how I’ve set it up.

language: ruby
rvm:
 - 2.2

Since Jekyll is built on Ruby I set the language to ruby. Depending on what version of Jekyll you’re using you can change rvm to meet your needs. I went with 2.2 since that’s the latest Travis CI provides.

sudo: false

This enables quicker build start times using the new container-based infrastructure.

branches:
 only:
 - master

Fairly obvious, build only from the master branch.

cache:
 bundler: true
 yarn: true
 directories:
 - node_modules # NPM packages

Travis CI pulls down and installs gem and Node.js modules before every build. Depending on what you have in your Gemfile and package.json files this can take a bit of time.

The above lines enable caching of these dependencies eliminating this installation step.

addons:
 apt:
 sources:
 - ubuntu-toolchain-r-test
 packages:
 - g++-4.8

env:
 CXX=g++-4.8

Enables the GCC, GNU Compiler Collection using APT Addon and a newer version of gcc/g++ to properly install Sharp.

Travis CI build lifecycle

My build lifecycle breaks down like this:

Clone repo and any submodules.
Install apt addons.
Install Ruby gems.
Upgrade Node.js and install Yarn + Node modules.
Run Gulp production build task gulp build --prod.
Decrypt private SSH keys needed to rsync files to my server.

Run Gulp deploy task:

deploy:
 provider: script
 skip_cleanup: true
 script: gulp deploy
 on:
 branch: master

With everything configured I no longer need to build locally and deploy. I can merge in comments or make small edits to Markdown files directly on GitHub, and automatically trigger a site build/deploy.

If there’s a problem Travis CI will notify me, otherwise in ~15 minutes (or however long the build takes) any changes committed will be live on the site.

Pagination upgrades

Looking to wring a little more #WebPerf juice out of my site, I went after category and tag archive pages next. Depending on the tag, these index.html pages could be quite hefty due to the amount of HTML needed to display hundreds of post teasers.

To trim them down in size I needed a way of paginating these pages into small chunks. Jekyll has an official pagination plugin, but unfortunately it’s limited (and deprecated) in what it can actually paginate. Jekyll Paginate v2 on the other hand is fully featured, backwards compatible, and actively being worked on.

In addition to paginating posts it can handle: collections, categories, tags, and locales (useful if you have a multi-language site).

It doesn’t stop there though! It has a built-in generator called Auto-Pages to create tag, category, and collection archives. Which unlike Jekyll Archives, can all be paginated.

With a few changes to my _config.yml file and adapting my Jekyll Archive layout to work with Jekyll Paginate v2, I was ready to roll.

# Plugin: Pagination (jekyll-paginate-v2)
pagination:
 enabled : true
 debug : false
 per_page : 15
 path : "/page/:num/"
 title : ":title - Page :num of :max"
 limit : 0
 sort_field : "date"
 sort_reverse : true

# Plugin: Auto Pages (jekyll-paginate-v2)
autopages:
 enabled : true
 categories:
 enabled : false
 collections:
 enabled : false
 tags:
 enabled : true
 layouts:
 - "autopage_tags.html"
 title : ":tag" # :tag is replaced by the tag name
 path : "/tag/:tag"

For category archives I created my own bespoke pages since there are only a handful of them. Mostly because it was easier to customize them than generating with Auto-Pages.

Step 1: Create an archive page… let’s use my Articles archive as an example. I like to keep all of my source pages grouped together, so I created articles.md and placed it in a folder named _pages.

Step 2: Enable pagination and define what categories it should filter, in this case articles by adding the following YAML Front Matter to articles.md.

pagination:
 enabled: true
 category: articles

Step 3: Output the posts by looping through the paginator.posts array. A simple example would look something like this:

<ul>
 {% for post in paginator.posts %}
 <!-- what you want to output. title, url, image, etc. -->
 <li><a href="{{ post.url }}">{{ post.title }}</a></li>
 {% endfor %}
</ul>

And for “next/previous” navigation links you can do something like this:

{% if paginator.total_pages > 1 %}
 {% if paginator.previous_page %}
 <a href="{{ paginator.previous_page_path }}">Newer Posts</a>
 {% endif %}
 {% if paginator.next_page %}
 <a href="{{ paginator.next_page_path }}">Older Posts</a>
 {% endif %}
{% endif %}

Lazyload tag

Another #WebPerf improvement was adding the ability to defer loading of images and video embeds.

To do this I created a custom Jekyll plugin using lazysizes to do some JavaScript magic.

Attribute	Required	Description
`data-src`	Required	Full path to image eg: `/assets/images/filename.jpg`. Use absolute URLS for those hosted externally.
`src`	Optional	Full path to low-quality image eg: `/assets/images/filename.jpg`. Use absolute URLS for those hosted externally. Defaults to inline transparent `.gif`.
`alt`	Optional	Image alternate text.

Example:

{% lazyload data-src="/assets/images/my-image.jpg" src="/assets/images/my-image-low-quality.jpg" alt="my lazyloaded image" %}

A Liquid version of this method is used in the hero image include to apply a nice blur effect as those large images are loaded by the browser.

Responsive video embed tag

Custom Jekyll plugin to embed a video from YouTube or Vimeo that responsively sizes to fit the width of its parent using /_plugins/video_embed.rb.

Embeds are also lazyloaded to improve page performance.

YouTube embed

To embed the following YouTube video at url https://www.youtube.com/watch?v=fFX1CUO472U (long version) or https://youtu.be/fFX1CUO472U (short version) into a post or page’s main content you’d use:

{% youtube fFX1CUO472U %}

Vimeo embed

To embed the following Vimeo video at url https://vimeo.com/97649261 into a post or page’s main content you’d use:

{% vimeo 34948855 %}

Simplified breadcrumbs

Previously I was using some Liquid voodoo to build a trail of breadcrumbs. This sort of worked because my site structure isn’t too complex. On the other hand it wasn’t flexible and didn’t allow for overriding crumbs with more descriptive labels.

Since my content hierarchy is shallow I decided to manually assign breadcrumbs to each post with YAML Front Matter.

breadcrumbs:
 - label: "Blog Articles"
 url: /articles/

Then using this Liquid and HTML it’s outputted in my layout:

{% if page.breadcrumbs %}
 {% assign crumb = page.breadcrumbs[0] %}
 <a href="{{ crumb.url }}"><strong>{{ crumb.label }}</strong></a>
{% endif %}

For multiple levels of breadcrumbs the following YAML and sample for loop should get the job started.

breadcrumbs:
 - label: "Level 1"
 url: /level-1/
 - label: "Level 2"
 url: /level-2/

{% if page.breadcrumbs %}
 <ul class="breadcrumbs">
 {% for crumb in page.breadcrumbs %}
 <li><a href="{{ crumb.url }}">{{ crumb.label }}</a></li>
 {% endfor %}
 </ul>
{% endif %}

Popular tags

Looking over my site’s analytics I came to the conclusion no one was clicking on the “this post was tagged” links, so I removed them. To make category pages more sticky and useful including tags seemed more useful. So with the following Liquid I was able to build a list of the most popular tags filtered on the current category.

{% assign filterCategory = page.pagination.category | default: page.category %}

<ul>
 {% assign tagLimiter = 0 %}
 {% for tag in site.tags %}
 {% comment %}create an empty array{% endcomment %}
 {% assign postsInCategory = "" | split: "/" %}

 {% comment %}loop over site.tags{% endcomment %}
 {% for post in tag[1] %}
 {% if post.categories contains filterCategory %}
 {% comment %}if a post is in the filter category add it to postsInCategory array{% endcomment %}
 {% assign postsInCategory = postsInCategory | push: post %}
 {% endif %}
 {% endfor %}

 {% comment %}poor man's tag limit on those that are frequently used{% endcomment %}
 {% if postsInCategory.size >= 5 and tagLimiter <= 5 %}
 {% assign tagLimiter = tagLimiter | plus: 1 %}
 <li><a href="/tag/{{ tag[0] | replace:' ','-' | downcase }}/" >{{ tag[0] }}</a></li>
 {% endif %}
 {% endfor %}
</ul>

On my Mastering Paper category page about the iPad app Paper by WeTransfer, you’ll see related links to tags like Paper app, iPad, drawing, etc.

Well there you have it, the complete tale of how I took something inherently simple and overly complicated it to suit my needs. If you have any questions after looking over the source ask away in the comments below.

Each task was run 3 times and averaged as the values produced by jekyll build --profile varied quite a bit. ↩︎
I classify “features” as large, often full-width images commonly seen in landing pages built with Bootstrap and other popular CSS frameworks. ↩︎
Sharp is super fast, but only resizes JPEG, PNG, WebP, and TIFF images… no GIF. It’s also a pain in the ass to install on Windows due to the node-gyp dependency. ↩︎
In the last couple of years several “cloud” solutions have emerged to make serving responsively sized images easier. Cloudinary (free plan), imgix (paid plans), and ImageEngine (free plan) just to name a few. ↩︎
Continuous integration is a DevOps software development practice where developers regularly merge their code changes into a central repository, after which automated builds and tests are run. ↩︎
There are several CI platforms and services out there that can automate testing, building, and deploying a JAMstack site. Netlify, Circle CI, Codeship, Travis CI, and GitLab CI to name a few. ↩︎
Branch updates, pull requests, or both. ↩︎

Optimizing and automating my Jekyll site build was originally published on Made Mistakes.

Styling language specific code blocks with Jekyll

2017-05-16T00:00:00-04:00

While inspecting the markup of some syntax highlighted code blocks generated by Kramdown and Jekyll, I noticed something I hadn’t before, language-lexer classes:

<div class="language-css highlighter-rouge">
 <pre class="highlight">
 <code>.foo { color: red; }</code>
 </pre>
</div>

This extra hook¹ on the <div> element opens up some interesting styling possibilities. A fun use case for this is styling code blocks to look like terminal windows. Assign terminal² as the language/lexer like so:

```terminal
```

Add the following Sass to your site’s stylesheet:

$terminal-window-height: 30px;

.language-terminal {
 position: relative;
 margin-bottom: 1.5em;
 padding: calc(#{$terminal-window-height} + 1em) 1em 1em;
 border: 1px solid $border-color;
 border-radius: $border-radius;
 box-shadow: 0 0.25em 1em rgba($base-color, 0.25);
 background-color: $base-color;

 &::before {
 content: "\2022 \2022 \2022";
 position: absolute;
 top: 0;
 left: 0;
 margin: 0;
 padding: (0.5 * $terminal-window-height) 0;
 background: mix($base-color, #fff, 25%);
 color: mix($base-color, #fff, 50%);
 font-size: (2 * $terminal-window-height);
 line-height: 0;
 text-indent: (0.5 * $terminal-window-height);
 }

 .highlight {
 margin: 0;
 padding: 0;
 background-color: initial;
 color: #fff;
 }
}

And you’ll get something that looks like this:

[15:34:01] Finished 'site' after 2.18 min
[15:34:01] Starting 'copy:site'...
[15:34:06] Finished 'copy:site' after 4.8 s
[15:34:06] Finished 'build:site' after 2.33 min
[15:34:06] Starting 'reload'...
[BS] Reloading Browsers...
[15:34:06] Finished 'reload' after 5.22 ms

This isn’t limited to language-terminal, and can be applied to any of the other languages and lexers supported by Rouge.

Apparently this was added into Kramdown a year ago. 😐 Who knew? ↩︎
terminal and console are aliases for shell_session and can be used interchangeably when assigning a language for syntax highlighting. ↩︎

Styling language specific code blocks with Jekyll was originally published on Made Mistakes.

Relic Scout

2017-04-19T00:00:00-04:00

Eko Wave, a company started by two pals and myself, just took the wraps off our first app — Relic Scout. Last week we launched a teaser site and couldn’t be prouder of the work that we’ve done so far.

I had a lot of fun creating the 8bit pixel art and applying a parallax effect to it using the jQuery plugin Plax. If you collect sports cards, magic cards, coins, or comics, you should check it out.

Style tiles

Relic Scout was originally published on Made Mistakes.

Eko Wave

2017-04-01T00:00:00-04:00

Eko Wave LLC is a company started by two pals and myself to provide value to niche consumers through well-thought-out applications.

When designing the logo I wanted something that played off of the word wave found in our name, while keeping with a color palette we established in Eko’s previous life.

Taking things a step further I created a basic style tile¹ document that helped me brainstorm how color, typography, and imagery fit and sell the concept to my partners. It would also serve as blueprint for me to design the site in browser — making for a more enjoyable and loose experience instead of being tied to a .PSD mockup I needed to CSSify² exactly.

The end result was a simple one page site that will ultimately grow as we build out our application and service portfolio.

Style Tiles are a design deliverable consisting of fonts, colors and interface elements that communicate the essence of a visual brand for the web. (Learn more) ↩︎
Is CSSify even a word? ↩︎

Eko Wave was originally published on Made Mistakes.

Basically Basic Jekyll theme

2017-03-29T00:00:00-04:00

Basically Basic is a Jekyll theme meant as a substitute for the default — Minima. Conventions and features found there are fully supported by Basically Basic, with a few enhancements thrown in for good measure:

Clean responsive design with six customizable skins
Curriculum Vitæ/Resume layout powered by JSON Resume
About page layout
Disqus Comments and Google Analytics support
SEO best practices via Jekyll SEO Tag

Live preview

 srcset="https://mademistakes.com/images/basically-basic-theme-menu_hu11938899852185244636.png 300w, https://mademistakes.com/images/basically-basic-theme-menu_hu8761160464118511264.png 620w"
>

 srcset="https://mademistakes.com/images/basically-basic-theme-cv_hu1206984904495914484.png 300w, https://mademistakes.com/images/basically-basic-theme-cv_hu10907596805391693609.png 620w"
>

 srcset="https://mademistakes.com/images/basically-basic-theme-alternate-skin_hu2210136705519057760.jpg 300w, https://mademistakes.com/images/basically-basic-theme-alternate-skin_hu3515784419130727665.jpg 620w"
>

Usage

To learn more about how to install, configure, customize the look and feel, create a curriculum vitæ/resume page, and some other junk, read up here.

Troubleshooting

Need help setting up the theme or getting it configured? Search the discussions or issues on GitHub. Having trouble installing or using Jekyll, the Jekyll Talk forum is a good place to ask for help.

License

This theme is free and open source software, distributed under the MIT License.

Basically Basic Jekyll theme was originally published on Made Mistakes.

Accessing static files in Jekyll

2017-01-30T00:00:00-05:00

While investigating ways of using static files with Jekyll for a site prototype I was building, I learned that site.static_files was a thing. What is it and why you should care? Let me take a minute to share…

According to the official Jekyll documentation, “a static file is a file that does not contain any YAML front matter. These include images, PDFs, and other un-rendered content.”

The useful bit — every one of these static files becomes accessible to Jekyll when looping through site.static_files. There aren’t many reasons why you’d want to do this, but if building “plugin-free” image galleries is one of them — here’s how.

Organize static files

Let’s say you have a folder (named gallery-1) of images you want to display together on a post or page.

├── assets/
│ └── images/
│ └── gallery-1/
│ ├── foo.jpg
│ ├── bar.gif
│ └── yaz.png

Start a loop

Using Liquid¹ you’d start by looping through site.static_files and then narrow down the files based on their paths. In this case we only want to show those images that live together in assets/images/gallery-1.

{% raw%}{% for image in site.static_files %}
 {% if image.path contains 'assets/images/gallery-1' %}
 <img src="{{ image.path }}" alt="">
 {% endif %}
{% endfor %}

Which will generate into the following HTML:

<img src="assets/images/gallery-1/bar.gif" alt="">
<img src="assets/images/gallery-1/foo.jpg" alt="">
<img src="assets/images/gallery-1/yaz.png" alt="">

Build an image gallery with Liquid

What if you’d rather spit out a group of thumbnail² images that link to a full-size version? Completely achievable using the above method — if you are careful to name these files in a predictable way.

Start by creating thumbnail versions of each image however you’d like. The important part here is to be consistent with the naming of these files. For the sake of this example I’ll be adding the suffix -th to each filename and storing them in the same location as the full-size assets.

├── assets/
│ └── images/
│ └── gallery-1/
│ ├── foo.jpg
│ ├── foo-th.jpg
│ ├── bar.gif
│ ├── bar-th.gif
│ ├── yaz.png
│ └── yaz-th.png

Assuming a thumbnail and full-size image share the same base name, we can construct the gallery’s HTML with the following:

{% for image in site.static_files %}
 {% if image.path contains 'assets/images/gallery-1' %}
 {% unless image.path contains '-th.' %}
 <a href="{{ image.path }}">
 <img src="{{ image.basename | append: '-th' | append: image.extname }}" alt="">
 </a>
 {% endunless %}
 {% endif %}
{% endfor %}

Now you may be wondering where basename and extname came from… simple. Each static file contains metadata accessible via Liquid with the following variables:

Variable	Description
`file.path`	The relative path to the file, e.g., `/assets/img/image.jpg`
`file.modified_time`	The time the file was last modified, e.g., `2016-04-01 16:35:26 +0200`
`file.name`	The string name of the file e.g., `image.jpg` for `image.jpg`
`file.basename`	The string basename of the file e.g., `image` for `image.jpg`
`file.extname`	The extension name for the file, e.g., `.jpg` for `image.jpg`

Feedback and improvements

In the end looping through site.static_files became an easy way spitting out a folder of files without having to hard code <img> elements. Sure there are a million different ways to do this with Jekyll, but this served a need and was a quick hack.

Curious if others are using static files in cool and interesting ways. Feel free to let me know in the comment section below if you are.

Liquid is an open source template language created by Shopify and written in Ruby. ↩︎
Thumbnails are reduced-size versions of pictures, used to help in recognizing and organizing them, serving the same role for images as a normal text index does for words. ↩︎

Accessing static files in Jekyll was originally published on Made Mistakes.