this site

Whenever starting a project it can be quite helpful to define goals and then make decisions oriented around them.

The content of https://www.esetroc.com consists of static info and a blog - html, css, and perhaps a tasteful amount of javascript.

Therefore, our goals can be divined by considering what kind of workflow we want to have for updating that info and adding new blog posts. We want to...

• Use a terminal and CLI based workflow.
• Write content and blog posts in markdown.
• Use html templates to improve dev experience without having to use a lot of javascript tooling.
• Be able to build the site and fill the templates ahead of time such that we have some public directory of static files that are easy to host.

decision: Zola

Zola is a great static site generator. Zola lets us handle the goals outlined above with ease.

We can write our content in markdown and then run zola build to convert the markdown into html according to predefined tera templates. Tera is similar to popular jinja templates.

extra nice things

There are some additional attractive features that I greatly enjoy:

1. zola serve with hot reloading whenever content, templates, or styles change.

2. Easily generate feeds, either atom or rss. This site uses atom.

3. Easily generate a sitemap.xml and robots.txt.

stumbling blocks

I did find a couple of instances where my experience using zola felt a bit strained:

1. I was running into situations where a markdown "content" file is just a link to the template. And then the template itself would hold the content. This would happen when the layout I wanted was more complex than what you get by default with writing only markdown. Things like grouping related elements into a single <section> or <div> require adding your own into the markdown. The alternative to this is to include a bunch of html in the markdown which in my opinion is not any better.

2. I wish there were a better disconnect between content directory structure and site url paths. I find that I want to put the blog posts into subdirectories for internal organization reasons but then have those posts still be part of the blog section so that creating the list of posts on the main blog post retains a good developer experience.
   You can customize the path of a content page by setting it in the front matter, but then you must also explicitly set the template and the page will no longer be part of a section.

3. It's funny how quickly writing logic in templates becomes unsightly.