How to break (and rebuild) the Jamstack
Tags: webdev, tips, jamstack, learning
Published: 2020-12-26 14:45:16

---
title: How to break (and rebuild) the Jamstack
description:  "My approach to 'minimum viable build' posts"
published: true
date: 2020-12-26 08:00:00 UTC
tags: webdev,tips,jamstack,learning
canonical_url: https://katiekodes.com/break-rebuild-jamstack/
---

How do I make the codebases behind my minimum viable build tutorials?

## ID the magic words

It’s been joked that [naming things is one of the hardest problems in computer science](https://martinfowler.com/bliki/TwoHardThings.html), so I like to figure out why authors of existing Jamstack-ready codebases used the words they chose.

When writing a brand new CMS content model or theme from scratch, I explore how thorougly I can avoid using any of the following words when naming file, folders, variables, map keys, objects, functions, and classes:

- slug
- permalink
- url
- path
- theme(s)
- template(s)
- layout(s)
- include(s)
- component(s)
- page(s)
- post(s)
- name
- title
- data
- content
- body
- head
- header
- footer

This challenge helps me identify “magic words” that serve as handy shortcuts in content management systems or [static site generators](https://dev.to/katiekodes/what-is-a-static-site-generator-350o).

> While I’m fine in 11ty and Gatsby, I still haven’t found a way to make Jekyll generate a URL from the value assigned to a Markdown file’s front matter key of `afterTheDomainName` without [duplicating the value in the file’s filename or in a front matter key called `slug` or `permalink`](https://jekyllrb.com/docs/permalinks/).
> 
> Have you?

Slowly reintroducing common names can reveal unexpected conflicts between various tools’ magic words.

> Attempting to use the word `slug` when building a Jekyll theme that I was also trying to make compatible with Stackbit CMS, I discovered that `slug` seems to have special behavior in a `stackbit.yaml` file managing new-Markdown-file creation.
> 
> I haven’t finished exploring, but this might mean avoiding the word `slug` in my Markdown data or Jekyll theme, instead using filenames or `permalink`.

Don’t forget: it’s not a great idea to leave strange names like `xyzzy` or `afterTheDomainName` sprinkled throughout your data or template as you build a real theme. Look around other people’s open-source code, find the standards, and consider naming things accordingly.

## Meet in the middle

Typically, I work both “up from scratch” and “down from existing examples” concurrently.

### Up

1. Starting with an empty folder, I tease out how few files besides `index.html` a static site generator will let me use to make a single web page from it.
2. Next, I try using an `index.md` file containing a front matter property of `message: Hello World`, without any content below its front matter, and some layout templates containing my HTML, to see how few files I need to generate a single web page. 
  - _(The notion of a single primary content area isn’t always easy to translate to equivalent headless CMS content models, I don’t usually bother to figure out how a static site generator uses it. If I do, I make sure I understand the impacts on my theme of trying to change it to work with a headless CMS.)_
3. Next, I see if I can rename and move that file to something more like `/allMyMarkdown/onlyPage.md` and still render the page to the web site’s root domain.
4. Then I see if I can use a `mySinglePage.json` to do the same thing.
5. I try playing with multiple `.md` or `.json` files, using some property of them to determine output URL, and build multiple pages within a site.
6. I try to repeat these steps, pulling the data from which I intend to build my site from a headless CMS’s API rather than from within the same filesystem as my SSG template configuration files.

### Down

I’m no genius, so I usually tear apart other programmers’ open-source themes to achieve the goals above.

- How many files can I remove from this Sanity-11ty starter, and how many lines of code can I remove from each file, and still make it work?
- What do all these Contentful-Gatsby and Contentful-Hugo starters seem to have in common that comes down to the essence of “talking to Contentful’s API”?

## Vary deployment

Deployment itself is something that needs to be figured out – “minimum” codebases may vary by deployment environment.

- CloudCannon builds a Jekyll site for me without my providing it a `Gemfile.lock` _(or even a Gemfile? can’t remember)_.
- Netlify requires a `Gemfile` for sure, and I believe also a `Gemfile.lock`. A `netlify.toml` file rarely hurts, either.
- Building and running a web site on my personal computer with a static site generator requires installing a massive Ruby, Node.js, or Go codebase.