Zettlr as a Blogging Tool

A few years ago I decided to break up my very complicated life into three streams of online consciousness. I’m a painter, so I created a separate zedshaw.art website just for my art. I’m a programmer, so I created the blog you’re reading right now and a separate twitter account @lzsthw just for the programming and technology parts of my life. I then created domains for a few other streams of my life, such as music, and ranting about technology and then...realized I could never manage all this junk.

Four or five different blogs, that I attempt to write in at least once a week? I mean, I’m a huge blabber mouth and can type like a demon but just the management of that many blog servers, git repos, or code projects took up too much time. I needed to automate as much of this as possible, and make it so that I just write in one place, on my computer, and not have to bounce around to 20 directories and servers doing random things to get a blog post up.

I’ve been slowly building out this very website at learnjsthehardway.com to be the basis of my future blogging and media hosting platforms. My goal is to make it so I can write locally on my computer and “things get done”. I save a file, maybe push one button or a key sequence, and the entire world gets an update from all the many faces of Zed. It’s been slow, but it’s coming together. I can now just push a simple markdown file to a git repo I control, and everything is done to make it happen. The only problem I had remaining was how on earth was I going to edit the .md files for all the different blogs I wanted to work on?

Enter Zettlr

I’d read about an information gathering and organization system called The Zettelkasten method, and an online friend gave me a course for using it. It’s an interesting way to organize your thoughts, especially if you have mild ADHD like me and simply walk through life randomly knowing things you can never find later. If you need to collect and combine random pieces of information then you should read about the method at zettelkasten.de to see if it will work for you.

I was trying it, using a few tools, but most of the tools were online only and I really didn’t have time to go to a website. One day, this kind person on Twitter mentioned a “Zettelkasten Editor” named Zettlr that I should try. It turns out, Zettlr is much more than a text editor for an obscure academic writing system. It really is almost a full “markdown IDE.”

Zettlr for One Blog

The documentation for Zettler is absolutely amazing, so to learn Zettlr just read their docs at https://docs.zettlr.com/en/guides/guide-ide/. What I’m going to show you is how to set Zettlr up so that you can write for one blog. This assumes that you are using something that will generate your blog for you off of a git push or similar file upload. If your blog is in Wordpress or similar online system then this won’t work at all. I’d also ask why you’re running a huge PHP application with a database just to post what’s basically a bunch of text files but that’s a whole other rant on another blog.

Options to Set

1. Setup your Zettlr following their instructions for using zettlr as an IDE, but only set a few options I mention here to get started. I tried their "Vim Mode" and it’s the Vim mode someone who hates Vim would create, so I don’t use it.
2. Go to the Autocorrect tab and disable it or at least turn off the "Magic Quotes". Magic Quotes are where you write the fancy curly quotes invented in 1890 to make books look fancy, but which cause nothing but trouble for programmers because they cause syntax errors. Trust me on this. One day you'll have some problem with something you wrote and you'll scour every line only to realize that " (double-quote) you thought was a standard double-quote is actually a garbage magic quote.
3. In Editor set it up for how you like to do your distraction free mode. I mute lines I'm not currently writing, but disable automatically closing parenthesis. In fact, if you could find all the ways Zettlr is "helping" you should disable them. They really don't help (more on that later).
4. Be sure to save your settings.

Adding the Blog

Next you need to add your blog to Zettlr so you can edit it. In the top right as shown here:

The open-folder icon is the one to press, and then you find your directory. You'll notice I have a directory named Blogging but it's not really where my posts are located. They're in the super helpfully named posts and I'll explain that in the next step. Once you add that, and assuming you followed the instructions for setting up Zettlr as an IDE then you should see that second pane with your blog posts listed. You can see all the posts from this blog there currently.

Distraction Free Mode

Next you just click on the post you want to work on, or click the + to add a new post to work on. Zettlr has an excellent distraction free writing mode that helps you work on just the thing you're writing and makes most of the UI go away. On the Mac I do cmd-J to toggle in and out of it. I also up the font size significantly since I'm writing on a giant screen on their tiny default font is too small. You can do it like in a browser with cmd-- (minus) and cmd-+ but just remember it does not remember that setting. You'll have to do that every time.

Zettler for All Blogs

Once you have one blog added, and you're comfortable working with it, you can then add as many different directories as you like. From the screenshot previously you can see I also keep a journal, which is a programming journal I write with what I've done all day. It also keeps my Zettelkasten notes as I run into random bits of information I need to maintain.

The one huge failing of Zettlr for managing multiple blogs is that it does crazy things with symlinks to figure out their true source, then ignore them. For those who don't know a symlink is a way to make an alias of one directory in a different directory. You can make a symlink like this:

ln -s ~/Projects/my-blog ~/Blogging/

This will create a "soft" symlink, which will put a fake directory named my-blog in the directory ~/Blogging. I thought I could do this and then have a dream setup where I just start Zettlr and go to "Blogging" and all my different blog .md file directories are right there.

Nope. The directories disappear, don't show up, get ignored, and if you add the symlink as its own directory then Zettlr tries to "help" and find the true file's name then add it there. This behavior completely violates the entire point of a symlink. A symlink is supposed to be ignored by all software and treated like a new directory. You have to actually write a lot of code to break through a symlink and Zettlr actually does have a lot of code to do just this. Looking in their repository I see they have tons of code like this:

node_modules/glob/sync.js
259:  var isSym = lstat && lstat.isSymbolicLink()
455:    if (lstat && lstat.isSymbolicLink()) {

node_modules/glob/glob.js
512:    var isSym = lstat && lstat.isSymbolicLink()
754:    if (lstat && lstat.isSymbolicLink()) {

node_modules/archiver-utils/node_modules/glob/sync.js
259:  var isSym = lstat && lstat.isSymbolicLink()
455:    if (lstat && lstat.isSymbolicLink()) {

node_modules/archiver-utils/node_modules/glob/glob.js
512:    var isSym = lstat && lstat.isSymbolicLink()
754:    if (lstat && lstat.isSymbolicLink()) {

That's a quick search for isSymbolicLink, and if you're writing your code correctly you shouldn't be doing this at all except in cases where security is involved. There's no reason a simple markdown editor should be subverting the symlink to "help" me. The code is riddled with these if-statements checking if every file and directory is a symlink.

Is it needed? Is there something about node that makes symlinks weird? Let's try stat on one:

> fs = require('fs');
> l = fs.statSync('ljsthw')
> l.isDirectory()
true
> l.isFile()
false
>

As you can see, the ljsthw symlink is handled by Node.js correctly. It is treated like its own directory, is not a file, and there's no problems with this. The reason Zettlr has a problem is it's using another function fs.lstat which gets the information of the symlink itself, then they go through a lot of code to bust through the symlink, find the real file, and just generally destroy the entire point of symlinks.

The other problem this behavior causes it it's not portable. Windows doesn't have the concept of a symlink, so all the code to do this super weird symlink busting also then needs to compensate for the special case of Windows. It's my belief that ripping all of this symlink code out, going with plain old fs.stat and leaving the symlinks alone, would make Zettlr much simpler and work better across platforms.

Why the Symlink Matters

My idea setup would be to have a nice directory like this:

~/Blogging/
    ljsth
    zedshaw.com
    zedshaw.art
    WIP
    Notes

Then I have one place I go, but each of these directories a symlinks into only the blog posts residing in the git repos I use for these projects. Because Zettlr does this weird symlink busting (for no reason I can see), I can't do that. I can make the symlinks, but then I have to add them outside of the Blogging Zettlr directory, and then Zettlr follows them and finds their true name, and that's why you see posts instead of ljsthw.

The Code is Wonderful

I grabbed the code from the Zettlr github project and I was blown away. Given my complaints above you'd think I thought the project was horribly written but quite to the contrary, I think it's a project to study. I was able to grab their code, install dependencies, and build an entire release of the Zettlr project for Mac, Windows, and Linux in about 10 minutes. That's amazing for an open source project, and I am totally going to study how they're doing this and copy as much as possible.

The code is also fairly decent given how complex it is. They're using Vue.js so it's not too bad to go read the components and mess with the UI. They also use fairly readable straightforward JavaScript code. I had a full mind to just fix this stupid symlink think they're doing, but as I dug into it this seems to be some feature that someone is very proud of since it's infected everywhere and would require most likely a massive change in governance to get removed. I'll leave it to them to try to fix it, but not holding my breath they ever will.

Important Zettlr Features

Zettlr's documentation is also something that is a real gem for an open source project. It makes sense that a project used for writing documentation would have really great docs written in multiple languages. Some of the best features I found were:

1. Built-in pomodoro timer up in the top right. It's very subtle, but you can see a little circle up top.
2. When attachments work, it's very nice to see all your media right there.
3. Being able to create a project and have Zettlr generate an entire directory of contents into one single document.
4. Reasonably snappy and fast for an Electron app.
5. Built in mermaid support in the latest version.
6. Very nice tagging feature that help you organize and find documents based on tags, but also click on tags to do searches right away.
7. Great editor that's kind of a 'half-wysiwyg' style. It still looks like markdown, but you'll get some nice formatting to help you figure out what you're writing.
8. Very nice distraction free mode that gets out of the way and lets you work.

Annoying “Features”

Zettlr is great, but there are some very questionable usability features that I feel need to be addressed. I've already talked at length to the weird symlink busting, and honestly I'd love the explanation for why they're even bothering with that. I'm sure it's some weird edge case like, "Well, one person on our project runs a PDP-11 and...." Until then, here's my list of annoying things about Zettlr:

1. It follows that trend of trying to "help" you paste things you copied from the web. If you select some text from a browser or anything with textual formatting it will "help" by adding what it thinks you would want to write to paste that to look the same. It fails miserably at this and mostly just trashes the text you meant to paste. The solution for now is to always use shift-cmd-v to paste, but this is backwards. The normal case should be that I paste only text.
2. Related to this, if you start a link text with [Some Text]( then you try to paste a link, Zettlr tries to "help" and pastes in the whole link twice, so you get [Some Text]([http://coollink.com](coollihk.com)). Again the solution is to shift-cmd-v but please oh please give me an option to switch this. Default pasting formatting is the absolute devil.
3. It doesn't remember your font size. On the plus side, it doesn't think ctrl-scrollwheel is the best way to zoom text like all browsers do, but it's irritating not having a font size setting that's permanent.
4. I have no idea why the images directory setting never works at all, but using the attachment right side bar is a mediocre experience. You pretty much just drag images into Zettlr then deal with it yourself.
5. Zettlr can use mermaid do to complex visual graphs, but can't display a bunch of media that a browser based editor should be able to display.
6. If you wonder why my instructions about adding your blogging directories is kind of weird, it's because Zettlr is trying to do everything it can to break symlinks. In fact, I think the whole editor would be about 30% simpler if they gutted every attempt to figure out what symlinks are and just treat them as the aliased directories they're supposed to be. I'd say 90% of the time some code is using lstat they are just wrong. A symlink is my organizational technique for directories, and it's not your place to follow it and root out it's true name.
7. The way you add new documents could be better. It'd be way better to be able to just cmd-shift-n or similar to have it drop a link where I'm writing, possibly with a new generated id, and then alt-click will create that file if it doesn't exist. You can use cmd-L to put the current document's ID in, but that's just useless and used maybe once. Meanwhile, linking to documents you haven't created yet so you can go back and make them is a very common operation, especially in a Zettelkasten

You can see that the general theme in my complaints revolves around Zettlr trying to be too smart. So far I'm loving it, but there seriously needs an option for Zettlr to be more "dumb". Don't try to format or alter my pastes at all and don't mess with symlinks.

Conclusion

Zettler is fantastic, apart from a few annoyances. The creators of Zettlr shouldn't take my criticism to mean I think it sucks. It just means I have some distaste for their decisions to subvert a few common things about computers (like symlinks). If you're looking for an editor for you blog, a research tool, and organizational tool it's loaded with great features. It even has a pomodoro timer built in for those of you who like that time management approach. I'd say, definitely give Zettlr a try for blogging and managing your infovore lifestyle, but if you have your own directories and don't want Zettlr's idea of how they should be, then you'll run into some annoyances.