developing my site with eleventy - part 2

read the other posts in the series:

part 1
part 3

recap

what is a static site generator?

A static site generator (SSG) is a piece of software that helps developers create websites more efficiently using reusable templates, layouts, and content that are compiled to produce complete webpages. SSGs compile all of the website's pages in advance so that they are ready to be served to a user even before they are requested. This can potentially benefit page load times, website security, and server load.

why did I choose eleventy for developing my site?

Two primary reasons:

• Eleventy comes highly recommended by leaders in the JAMstack industry.
• It's un-opinionated in regards to the directory structure, templating formats, and data/content hierarchy.

accounts and tools I use to build and run my site

1. Github
2. Netlify
3. Forestry CMS
4. Custom domain name purchased through DreamHost
5. A code editor (mostly Atom)
6. A good terminal (iTerm2 on Mac, new Terminal app on Windows)

The only monetary expense is the domain name. Everything else is freeeeee (for my low usage levels and more basic use-cases 😉)

And to be honest, if I wanted an even simpler or cheaper set up I could drop the CMS and the custom domain, and use the built-in text editor and terminal applications on my computers.

my eleventy set up

To give myself a bit of a leg up in starting my Eleventy journey, I cloned Phil Hawksworth's ElevenTail starter scaffold for Eleventy projects. After taking some time to study how he had done things, I proceeded to strip out almost everything in there except for the directory structure, npm scripts, and one or two helper scripts 😂 I wanted to roll my own style-sheet using my beloved Stylus CSS pre-processor and also wanted to keep JavaScript to a minimum. I also didn't understand a bunch of the stuff he had done, and I'd rather not have unused and misunderstood code floating around. I have no doubt that his setup is much more robust than mine, but I need to go through the process of figuring it all out for myself.

the structure

My basic git repo directory structure looks like this:

/
+-- dist
|   |— the entire built site ends up in here
|
+-- src
    +-- site
    |   +-- _data
    |   |   |-- .json data files
    |   |
    |   +-- _includes
    |   |   +-- components
    |   |   |   |-- reusable components in .njk format
    |   |   |
    |   |   +-- layouts
    |   |   |   |- primary page layouts
    |   |   |
    |   |   |-- footer.njk
    |   |   |-- header.njk
    |   |
    |   +-- css
    |   |   |- styles.styl
    |   |
    |   +-- fonts
    |   |   |-- webfont files
    |   |
    |   +-- images
    |   +-- js
    |
    +-- utils
        |-- Eleventy filters and helper utilities

the CSS

Phil Hawksworth's starter project had Tailwind CSS set up and ready to go. I have not yet used Tailwind but it looks great. I did some reading about the idea behind CSS utility classes and thought it sounds like a great way to keep the CSS footprint from getting out of control. So as I usually do, I decided to write my own from scratch instead of using an established tool. This is how I learn. I "reinvent the wheel" on purpose. I find I learn so much by doing it this way and then when I graduate to using the more advanced tools out there I can really appreciate how they work and the problems they solve. It's sometimes a slow way to learn, but I find leads to a much deeper understanding of the concepts.

I have been using Stylus as my CSS pre-processor for a while now and still love it. It's powerful but doesn't force a particular syntax or code style. I seem to gravitate towards unopinionated tools 🙂

the templating

Until this project, I had never used an HTML templating language 😲 Eleventy allows you to choose from quite a large number of the more popular templating languages. While researching which to use, I started seeing a lot of people talking about (and raving about) Nunjucks. And the Eleventy documentation uses it in almost all of its code examples (the other it always shows is Liquid, which is syntactically quite similar to Nunjucks). So I went with that.

I am in love.

Why-oh-why did I wait this long to try a templating language?

the CMS

I really don't need a CMS for this little site. I am quite happy to write posts in markdown text files and commit them from a terminal. I am happy to make copywriting and data changes directly in my templates and commit them manually.

But, I build sites for clients. They are often non-technical clients who will not be happy with such a setup. And so in the interest of providing a better service to my clients, I decided I must learn how to integrate a headless or git-based CMS with a static site.

I went with Forestry for this site as git-based CMSs seem to be slightly easier to grasp than API-driven headless CMSs (such as Strapi or ButterCMS).

I've learned a lot. I've learned that it's very important to spec a detailed content hierarchy before you start the integration. I've had to do a fair bit of retroactively designing my content hierarchy in order to make the Forestry experience seamless and user-friendly.

If you are going to use a CMS, I highly recommend choosing one and integrating it from the absolute beginning of your project. And make the effort to only ever make content changes through the CMS, this helps to avoid git conflicts.

conclusion

That's my Eleventy setup. If you have any experience with these things I am sure you will see that I still have much to learn. But it's been a great experience so far. A huge improvement over hand-coding every page of a website like I have done once or twice 👻 Also it's nice to feel in control, which I definitely don't feel when building a WordPress site (yet, I am learning a lot on that side as well).

Let me know on Twitter (@MrNygaard) if you have any suggestions or critiques 🙃