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.

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.