passthejoe by Steven Rosenberg - static site generators

Custom note names in QOwnNotes

2026-04-02T00:00:00+00:00
Since QOwnNotes</a> takes its note name from the first line of every post, and the first line of every Zola</a> blog post is +++</code> due to the TOML frontmatter</a>, I'm going to have to deal with this on the notetaking end of things.
Naming the note by the Zola filename I want to use for the post would be the best outcome, and it turns out that is possible.
When you try to rename a note, you get this dialog:
If you want to rename your note you have to enable the option to allow the note filename to be different from the headline. </blockquote> The dialog leads you right there, but you can get there any time in QOwnNotes under Note -> Settings -> Note Folders</code>. I only have one note folder at this point, and it's called default</code>, so right there I click the box next to Allow note file name to be different from headline</code>, and that lets me rename my notes. It's a nice feature that it's allowed by note folder (and that multiple note folders are possible). To veer off-topic only slightly, one of the things I like about QOwnNotes is that it is a native application coded in C++ with the QT toolkit</a>. It's not an Electron app yet is still available for Linux, Windows, MacOS, FreeBSD and OpenBSD. Another point in QOwnNotes' favor for the purpose of creating posts for static sites is that when exporting, the program remembers the directory and file name you last used, which saves considerably on clicking and typing. It makes the export a fairly seamless part of my blogging workflow.


This is a Zola post that started in QOwnNotes
2026-03-29T00:00:00+00:00
Can I create a Zola blog post in a notetaking app and have it successfully move from the app to the live site?</p>
If you're seeing this, the answer is yes.</p>


A couple CSS tweaks makes Zola's Hook theme easier on the eyes
2025-08-19T00:00:00+00:00
I've had a few problems with the Hook theme</a> in Zola</a>. Some I fixed myself, even if they were eventually fixed by the theme writer/maintainer. It's all an opportunity to learn how Zola, the Tera template engine</a>, and HTML/CSS</a> work.</p>
I chose this theme due to functionality and simplicity, but as the entries have built up, the layout of the home page and archive page is looking a little cramped.</p>
To clear it up, I took away the text-decoration</code> from the a, a:link, a:visited</code> elements, added text-decoration</code> to a:hover</code> and added some padding to li</code>.</p>
Here are parts I changes in /themes/zola-hook/sass/_theme.scss</code>:</p>

</span>a</span>, </span>a</span>:link, </span>a</span>:visited {
</span>    </span>color</span>: </span>var</span>(</span>--accent</span>);
</span>    </span>text-decoration</span>: </span>none</span>;
</span>}
</span>
</span>a</span>:hover {
</span>    </span>color</span>: </span>var</span>(</span>--accent-highlight</span>);
</span>    </span>text-decoration</span>: </span>underline</span>;
</span>}
</span>
</span>li </span>{
</span>    </span>padding-bottom</span>: </span>10</span>px</span>;
</span>}
</span>
</span></code></pre>


Zola for Note Taking by Bhavani Shankar
2025-05-14T00:00:00+00:00
In his post, A simple setup for distraction free writing</a>, Bhavani Shankar goes over his workflow, which includes the Helix text editor (Vim-like but with more batteries included than Neovim) and Zola "for generating websites and taking notes."</p>
I keep trying the hot/new editors of the moment (or of the past 5 years ...), and I've been through Neovim, the GUI version Neovide and now Helix.</p>
Since I rely heavily on macros in my .vimrc</code>, and none of those macros work in the vimrc-like config for Neovim, and I couldn't find any documentation for Helix that mentions macros and how to do them.</p>
I'm guessing that the Neovim community is encouraging the configuration based on Lua rather than Vimscript, which is fine except that I don't know how to replicate my .vimrc</code> in either Neovim or Helix.</p>
If I want "distraction-free" writing, I can do that in Vim or the GNOME Text editor (which I'm using now).</p>
And of course I'm in favor of using Zola as a static-site generator, though Hugo would work just as well.</p>
One thing I did to make my publishing workflow more efficient is move a copy of my rsync deploy script into my main Zola directory. That way I can zola build</code> and then run the rsync script without having to change directories at all.</p>
As an aside, making simple scripts is the only way</em> to use rsync. And I almost always prefer rsync to using an FTP client. It's easier and faster.</p>
I could reduce the number of steps even further by writing a script that put the zola build</code> and rsync operations under a single command.</p>


How to create RSS/Atom feeds in Zola for your tags, categories and any other taxonomies you've set up
2025-03-17T00:00:00+00:00
In my effort to build out my own Zola site and get the Hook</a> theme to do what I want, I look at the After Dark</a> theme — which is maintained by the Zola team — for coding tips (i.e. things I can steal).</p>
I was in After Dark looking for something else, and I noticed that the theme's config.toml</code></a> has code that tells Zola to create separate RSS/Atom feeds for every category and tag you set up.</p>
Here is that code:</p>
taxonomies </span>= </span>[
</span>    {</span>name </span>= </span>"</span>categories</span>"</span>, </span>feed </span>= </span>true</span>},
</span>    {</span>name </span>= </span>"</span>tags</span>"</span>, </span>feed </span>= </span>true</span>},
</span>]
</span></code></pre>
(Strong hint:</strong> It's the feed = true</code> part)</p>
This is another great Zola feature that I'm going to take advantage of immediately. I should also probably just move to the After Dark theme so I get all of the good stuff out of the box.</p>
The next thing in After Dark that I want (and don't have) is the site search</a>. I could port that over to Hook, or just move to the theme that already has it. But I bet I can easily add it to my current theme.</p>
Before I leave this post, I'd like to point out that some work has been done on Hook since Zola 0.20 came out, and it looks like the template that allows rss.xml</code> and atom.xml</code> to be built</a> has been fixed. That is nice to see.</p>


In Zola, draft = true works in the front matter
2025-02-28T00:00:00+00:00
I have used draft = true</code> in my Hugo</a> front matter as long as I have been running that static site generator.</p>
Will adding draft = true</code> to the front matter of a Zola</a> post keep the system from building it?</p>
I tried it, and it works.</p>
To make the post appear, either delete draft = true</code>, or change it to draft = false</code>.</p>


Zola test: Can you group taxonomies in front matter?
2025-02-28T00:00:00+00:00
Can you group tags and categories under a [taxonomies]</code> section in your Zola post's front matter rather than listing them under taxonomies.tags</code> and taxonomies.categories</code>?</p>
Yes you can.</p>
This post's front matter went from:</p>
+++</span>
</span>title </span>= </span>"</span>Zola test: Can you group taxonomies in front matter?</span>"
</span>date </span>= </span>2025-02-28
</span>
</span>taxonomies</span>.</span>tags </span>= </span>[
</span>    </span>"</span>front matter</span>"</span>,
</span>    </span>"</span>toml</span>"</span>,
</span>]
</span>taxonomies</span>.</span>categories </span>= </span>[
</span>    </span>"</span>Zola</span>"
</span>]
</span>+++</span>
</span></code></pre>
to:</p>
+++</span>
</span>title </span>= </span>"</span>Zola test: Can you group taxonomies in front matter?</span>"
</span>date </span>= </span>2025-02-28
</span>
</span>[taxonomies]
</span>
</span>tags </span>= </span>[
</span>    </span>"</span>front matter</span>"</span>,
</span>    </span>"</span>toml</span>"</span>,
</span>]
</span>categories </span>= </span>[
</span>    </span>"</span>Zola</span>"
</span>]
</span>+++</span>
</span></code></pre>
The second one, with [taxonomies]</code> seems cleaner, and that's what I'm going to use.</p>


Observations about the Zola static site generator after a month
2025-02-25T00:00:00+00:00
I thought I'd have a lot more posts here over the last month than the one that appeared when I started this site. But aiming to make this blog more "real" and researched has stalled my effort to finish the entry on how I fixed my theme's RSS code so either or both of the atom.xml</code> and rss.xml</code> feeds render.</p>
That post will appear. Eventually. But now it's time for quantity, not quality.</p>
What's my general feeling</em> about Zola</a>? At this point I am mostly comparing it to (what I know about) Hugo</a>.</p>
At no time have I been a super-active Hugo blogger, but I have maintained Hugo sites with a handful of themes for a few years at this point. I always mean to write more</em>. I don't create as many social media posts as I used to, but I still write a fair amount (on ruby.social</a> and gts.passthejoe.net</a>.</p>
There's a certain ease in writing and publishing on social media sites. You type into a box, add a link and a few hashtags and click "Publish." Blogs have a lot of options, but it should still be easier to put an entry together that it is right now for everything from WordPress to Hugo and Zola. Social media software has taken away a lot of the friction</em> of putting your thoughts out into the world, and I think blogging should try to get in on that simplicity and ease.</p>
It's all about getting the idea out there quickly and with as little fiddling as possible.</p>
Could Zola help me in this regard? This part of the blogging workflow is just about the same in Hugo. Both are static site generators. One is coded with Golang, the other with Rust. For my purposes, that doesn't matter very much.</p>
Users of all the SSGs seem to gravitate toward a git-based workflow. You write the posts locally and commit them to a remote git repository, where a CI/CD system (continuous integration/continuous deployment??) builds the site and makes it available to a web server.</p>
That's more complexity than I want. I'm running my Zola site the same way I run Hugo: I have everything on my laptop — mirrored from there to two other local systems via Syncthing</a>. I write the posts, build the site and then send the public files to the web server via an rsync script.</p>
As I do when I discover (or return to) a static site generator, I look at all the themes and try to find something that looks and works as much like I want it to as possible.</p>
That part is harder than it looks.</p>
As I wrote in the first post</a> on this site, I went for the Hook</a> theme.</p>
It does fulfill a lot of my wants</em> in a blog theme, and since I've started, I have been able to:</p>

Add my byline to entries</li>
Fix the rendering of atom.xml</a> and rss.xml</a> feeds</li>
Use the [taxonomies]</code> section in front matter to simplify the use of categories and tags in posts</li>
Confirm that draft = true</code> and draft = false</code> works in front matter for posts</li>
</ul>
With Hook, I can easily add pages to the links list, either in config.toml</code> or in post front matter. Pages for tags</a> and categories</a> are already there. The main page</a> [won't be clogged with entries, and there's an archive page</a> where everything will live.</p>
I can run zola serve</code> to see how it's going to look, and then create the html with zola build.</code> It's all super fast.</p>
So far, the relative simplicity of Zola has been one of its biggest draws. I'm able to figure out</em> themes and modify them non-destructively</em> by copying template files from /themes/zola-hook/templates</code> into /templates</code> and working on them over there.</p>
And while Zola doesn't have a lot of documentation, it also doesn't have a lot of unhelpful documentation</code>. I'm picking up a lot by looking at other themes — especially those maintained by the Zola project</a> — and from the Tera template engine</a>'s own documentation</a>.</p>
Zola 0.20 was just released, and it's hard to see if there were any significant changes. The project moves slow. Releases aren't coming out all the time like with Hugo, and if the project stays slow and steady — as opposed to abandoned — I will be happy. Like Hugo, Zola is flexible and programmable. The same number of batteries are not included, but there are more than enough for what I'm trying to do.</p>
(To be continued ...)</em></p>


Hello Zola
2025-01-28T00:00:00+00:00
I have been experimenting with Zola sites pretty heavily this past week, creating and destroyed slightly south of 10 of them.</p>
I have been a Hugo user for a few years at this point, so the concept of a static site generator that runs with a single binary file is something I'm comfortable with. I tend to find Hugo themes puzzling</em>. I want to know how the pages come together so I can make the changes I want. Maybe Zola will provide that.</p>
The one thing that users talk about is the difference in the templating language between Hugo and Zola. Plus Zola is supposed to be a simpler system. Whether that's by design, or just because it's a younger project with fewer developers, I don't know.</p>
After looking at a couple dozen Zola themes</a>, I tried a few out. One thing I'm discovering from looking at themes is that you can modify one by pulling ideas and code from another.</p>
My theme requirements are:</p>

Simple, readable design</li>
Not heavy with JavaScript</li>
Not too geeky (as in don't show the Markdown #</code> in post titles)</li>
List at least a few posts on the home page</li>
Has working RSS (a surprisingly tall order, though I now know why), preferably with full text</li>
Has pages for a post archive, tags and categories</li>
</ul>
For now I'm using the Hook</a> theme. It hits most of these requirements pretty well, though it won't render an RSS feed until I figure out how to update the code.</p>
One of the cool features of Zola is the ability to override the templates in your theme by dropping files with the same template names and paths into your project installation's template file (in your local directories). I copied page.html</code> from /my-local-zola-directory/themes/zola-hack/templates</code> to /my-local-zola-directory/templates</code>, and from there I added the code needed to make an author's name appear on posts. I started with code from the after-dark</a> theme and added a line so the global author (set in config.toml</code>) would appear.</p>
Here is the code I added to /templates/page.html</code>:</p>
<</span>p class</span>=</span>"</span>secondary small</span>"</span>>
</span>    {</span>% if</span> page.extra.author </span>%</span>}
</span>        By {{ page.extra.author }}
</span>    {</span>%</span> elif config.extra.author </span>%</span>}
</span>        By {{ config.extra.author }}
</span>    {</span>% else %</span>}
</span>        By {{ config.author }}
</span>    {</span>%</span> endif </span>%</span>}
</span></</span>p</span>>
</span></code></pre>
That was enough to get my byline on this post.</p>
To explain the code, it's classic if/else if/else</code> logic that goes in this order:</p>
page.extra.author</code> is displayed if this code is in the front matter of the post:</p>
+++</span>
</span>[extra]
</span>author </span>= </span>"</span>Rex Reed</span>"
</span>+++</span>
</span></code></pre>
I haven't tested it yet, but I assume that config.extra.author</code> displays if that same code above is in config.toml</code>.</p>
And what's displaying on this post (for now anyway) is config.author</code>, which is in config.toml</code> like this:</p>
author </span>= </span>"</span>Rex Reed</span>"
</span></code></pre>
The Zola documentation for Page</a> is very helpful, especially in terms of what you can do with front matter on a post.</p>
Another page on the Zola documentation that I have been referring to is Configuration</a>, which goes over things that you can put in config.toml</code>. It lists all the defaults, which really helped me. That's where I learned how to tell Zola to generate RSS feeds and set an author name.</p>
I also learned from the Configuration page that if you flip from false to true on external_links_target_blank = false</code>, all of your links set with Markdown will automatically be coded with target=_blank</code> and rel="noopener"</code> and will open in a new browser tab when clicked.</p>
Another thing this page tells me is that the built-in search is pretty nice, and in a way I'm sorry my current theme isn't using it. I did try it with the after-dark</a> theme, and it is an impressive feature.</p>
The [slugify]</code> section on the Configuration documentation page</a> lists this Zola default:</p>
# Whether to remove date prefixes for page path slugs.
</span># For example, content/posts/2016-10-08_a-post-with-dates.md => posts/a-post-with-dates
</span># When true, content/posts/2016-10-08_a-post-with-dates.md => posts/2016-10-08-a-post-with-dates
</span>paths_keep_dates </span>= </span>false
</span></code></pre>
Once I saw this, I started doing my dates in file names like this — 2025-01-29</code> — instead of the way I usually do them: 2025_0129</code>. That cleaned up my URLs right away.</p>
It's interesting that the Hugo Bear Blog theme</a> that I'm using in Hugo right now</a> also cuts off the dates (which are on most of the files in my usual format (2025_0129</code>).</p>
I think</em> this is the code in hugo.toml</code> that makes this happen (but I can't be sure until I toggle it):</p>
[permalinks]
</span>  </span>blog </span>= </span>"</span>/:slug/</span>"
</span>  </span>tags </span>= </span>"</span>/blog/:slug</span>"
</span></code></pre>
It was quite a discovery with Hugo Bear Blog that this is something you could easily do. I really like having the dates in the file names because it helps me know how old a post is on my local computer without needing to open it and look at the date. But it's redundant on the live site where the blog generator puts dates on everything and renders it in order.</p>
I'm glad this is the default in Zola (and works when you code the dates right in your source files).</p>
Back to my RSS issue with Zola: I think I can coax the Hook theme into rendering an RSS feed. I know what the problem is: the options for RSS feeds in Zola changed in the 0.19 release, and there is old code in the theme. But can I fix it? I will try.</p>