Salesforce, Python, SQL, & other ways to put your data where you need it

Need event music? 🎸

Live and recorded jazz, pop, and meditative music for your virtual conference / Zoom wedding / yoga class / private party with quality sound and a smooth technical experience

How to break (and rebuild) the Jamstack

26 Dec 2020 🔖 jamstack tips web development minimum viable build
💬 EN

Table of Contents

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, 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.

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.

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.

Update: In response to this post, Alan Smith suggested names like p_ost and permalin_k and I love this idea. I spend too much energy inventing awkward synonyms like afterTheDomainName for slug, and Alan’s pattern definitely reminds me to avoid names I’ll forget in 3 weeks like xyzzy.

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.
--- ---