26 Dec 2020
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:
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
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
Don’t forget: it’s not a great idea to leave strange names like
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
permalin_k and I love this idea. I spend too much energy inventing awkward synonyms like
slug, and Alan’s pattern definitely reminds me to avoid names I’ll forget in 3 weeks like
Meet in the middle
Typically, I work both “up from scratch” and “down from existing examples” concurrently.
- Starting with an empty folder, I tease out how few files besides
index.htmla static site generator will let me use to make a single web page from it.
- Next, I try using an
index.mdfile 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.)
- Next, I see if I can rename and move that file to something more like
/allMyMarkdown/onlyPage.mdand still render the page to the web site’s root domain.
- Then I see if I can use a
mySinglePage.jsonto do the same thing.
- I try playing with multiple
.jsonfiles, using some property of them to determine output URL, and build multiple pages within a site.
- 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.
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”?
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
Gemfilefor sure, and I believe also a
netlify.tomlfile 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.