Learn static site generation with Stackbit
28 Aug 2021
Stackbit does it again: their blog is kicking out articles that are amazing resources for web developers picking up new technologies. Their latest series is called the Jamstack Journey, and it’s a really great deep dive into the concepts I was trying to explain with “What is static web hosting?” and “What is a static site generator?.”
Using 11ty – of which I highly approve as a teaching environment because Liquid & Nunjucks look so much more like plain-old HTML than React or Vue – Stackbit’s Sean C Davis goes into the minutiae of how to help your brain go:
- From a collection of
index.html,about.html,blog/1.html,blog/2.html, etc. files - To a fully componentized Squarespace-like architecture such as the one I illustrated last year at “WYSIWYG CMS-friendly Markdown.”
Step 1: Use an SSG at all
In “How to Convert Static HTML into Powerful Templates,” Sean helps you set up Eleventy to break out repeatable elements like <html> ... </html>, <header> ... </header>, and <footer> ... </footer> so that all you have left in index.njk, about.njk, etc. besides calls to {% include "footer.njk" %} and such are the actual important bits like <h1>Welcome to my home page</h1> and <p>I'm Katie, and I'm learning web development.</p>
Step 2: Eliminate plaintext from your HTML
Next, Sean points out that Welcome to my home page doesn’t really have any business in an H1 tag.
Instead, put it in a title attribute of a dataset separate from your HTML, and then use a syntax like <h1>{{ title }}</h1> in your HTML.
You’ll end up with files in your static site generator’s codebase that have extremely verbose “front matter” at the top (just look at Sean’s 64 lines of YAML in index.md!), but that’s a good thing – trust us.
Remember, I do the same thing to build a Wix-like experience at “WYSIWYG CMS-friendly Markdown.”
In fact, Sean doesn’t have anything but “front matter” left in his index.md – he moved all of the HTML to a separate home.njk file.
I love it.
Step 3: Use your front matter to componentize repetitive HTML
I’d never thought of doing things this way, but Sean makes an excellent point that once you’ve broken your content out of your HTML into a tree-like structure like YAML, it gets pretty easy for your eyes to skim through the YAML looking for redundancy.
And that that redundancy is exactly what will lead you to figure out which HTML you can organize by breaking it apart into for-loops and “include” calls to separate files.{% for ... %}{% include 'my_component.njk' %}{% endfor %}
Of course, you can look for redundant HTML and do the same thing, too, but I’d never explicitly thought of looking for the redundancy in the data first.
Sean uses the example of a list of “speakers” at an event – you’re going to want a speaker.njk include that gets called inside a for-loop. It’s the kind of work I started doing over at my web-site-kitwind-liquid repo, since when you copy and paste HTML from Kometa Kitwind’s Twilwind CSS components, you get a lot of redundant <li>...</li> tags and such that you’re responsible for breaking into repeatable templates yourself.
Honestly, you simply can’t build drag-and-drop-friendly Weebly-like Jamstack websites without putting in the work to “componentize everything.”.
And since Stackbit is a manufacturer of a drag-and-drop tool skin you can drop onto a Jamstack website … they’re all-in on writing free content that teaches developers how to componentize themes. (Otherwise, I suppose you couldn’t use their product!)
They even dedicated a section of their docs to Content Modeling and theme componentization tutorials.
Takeaway
I’m excited about this new “Jamstack Journey” series, and if you got any value out of my “What is a static site generator?” article, but aren’t sure how to take the next steps of componentization, I encourage you to visit the Stackbit blog and check out these new articles.
Nicely done, Sean.
