path: root/src/blog/logseq.html.erb

title: Switching from GitJournal to LogSeq
date: July 15, 2023
---
<p>
As mentioned previously on the blog, for a long time I was relying on
<a href='<%= path_to 'blog_gitjournal' %>'>
  GitJournal
</a> for note taking. There were quite a few reasons I really liked it:
</p>

<ul>
  <li>It's open source.</li>
  <li>Syncs with <code>git</code> (which I can selfhost).</li>
  <li>
    The underlying format is just MarkDown, which means that I can easily edit
    the notes on my laptop with my editor of choice.
  </li>
</ul>

<p>
But there's also some issues I kept running into:

<ul>
  <li>
    Search is not very good (in particular, there's no in-page search, only
    searching for notes that contain a certain string)
  </li>
  <li>
    The hierarchical organization of notes is nice and simple, but has its
    limits, not all relationships between ideas are tree-like.
  </li>
  <li>
    The <code>git</code> implementation on the mobile app has its problems. E.g.
    merge conflicts are not going to be resolved, sometimes leading to forced
    commits that remove notes. All of this can be resolved on a computer with
    access to the repo, but it can become a hassle.
  </li>
  <li>
    There's no easy way to link between notes, which could have been very nice.
  </li>
  <li>
    Some other bugs I've noticed, e.g. sometimes duplicate notes appearing, or
    others completely disappearing (could be caused by the git issues mentioned
    above, or the way I was managing notes computer-side away from the app).
  </li>
</ul>
</p>

<p>
None of these issues are absolute deal breakers, and I still think GitJournal is
a really nice solution that I can recommend, but all the slight annoyances led
me on a search for a potential replacement. If I didn't find anything better, I
would have been happy to stick with GitJournal, but maybe there's a note taking
solution somewhere out there that would suit me better?
</p>

<p>
If you do some research on note taking apps you'll be greeted with a flood of
content from "productivity" YouTubers, bloggers, etc. Turns out there's a ton of
options for different types of workflows and preferences, however most of them
are
</p>

<ul>
  <li>proprietary</li>
  <li>bloated</li>
  <li>
    for syncing, require registration with a SaaS startup that you have no idea
    how long it will stay in business, or how much of their monetization model
    depends on scraping your data.
  </li>
</ul>

<p>
Enter <a href='https://logseq.com/'>LogSeq</a>.
</p>

<h3> Enter LogSeq </h3>
<p>
Let me start off by saying that LogSeq is not <i>the</i> perfect solution for
me, but I'll go over my personal gripes with it later. First, let's talk about
what LogSeq even is and what's good about it.
</p>

<p>
LogSeq is an open source note taking application that is privacy-first,
outline-based, non-hierarchical, and features bidirectional linking. Let's break
that down:
</p>

<ul>
  <li>
    <i>Privacy-first</i>: all notes are stored as plain-text files on your
    computer. By default, there's no synchronization; in particular, there's no
    central server the app talks to.
  </li>
  <li>
    <i>Outline-based</i>: each line of text is a bullet point (and these can be
    nested), there's no plain paragraphs/headings like in MarkDown or basic
    HTML.
  </li>
  <li>
    <i>Non-hierarchical</i>: notes are not organized into a tree-like directory
    structure. Instead, each note is a separate page, and you organize your
    notes by linking/tagging between pages.
  </li>
  <li>
    <i>Bidirectional linking</i>: these links between pages go in two directions,
    i.e. when page A links to page B, page B will have a section of
    <i>backlinks</i>, making it easy to jump back to where B is referred from
    (be that back to page A, or any other pages that link to B).

    <ul>
      <li>
        This feature is inspired by another app, Obisidan, which you might be
        familiar with. Both Obisdian and LogSeq are touted by some to be good
        tools for building a so-called "second brain."
    </ul>
  </li>
</ul>

<p>
Some other features to mention:
</p>

<h4> Journal </h4>
<p>
LogSeq automatically creates daily journal pages. These can be used for
journaling or as a dumping spot of random ideas, links you encounter, notes to
jot down. Thanks to backlinks, if you include tags or links to topic pages in
your notes, you'll be able to find these seemingly chaotic daily notes when
looking at a specific topic later.
</p>

<h4> Plugins </h4>
<p>
There is a plugin interface, and an already fairly large marketplace of
community-built plugins available. Many are just visual tweaks you can add if
you like them, there's also a bunch of integrations with various other note
taking/productivity apps (which I personally don't use, but many find them
useful, from what I hear, in their workflows). There's really only one plugin
I'm using currently, more on that in the next section, but overall its nice to
see extensibility.
</p>

<h4> Synchronization </h4>
<p>
As mentioned, there's no synchronization enabled by default. There is a
recommended cloud sync option with LogSeq's servers, which respects your privacy
by end-to-end encrypting all your content, but you know me. I prefer to sync my
notes with <code>git</code>. Not only does this allow me to selfhost my notes,
it also gives me all the benefits of version control (history, a way to deal
with merge conflicts when dealing with multiple devices).
</p>

<p>
Since all of LogSeq's note files are just plain-text on your disk, setting up
git synchronization is trivial: just make the notes directory a git repo, add a
remote, and voilá.
</p>

<p>
Here's also where a plugin comes in useful: there's a <code>git</code> plugin
that makes it easy to commit, push, and pull changes from within LogSeq itself,
rather than having to switch between it and a terminal.
</p>

<p>
Note: LogSeq does have a separate built-in version control feature that's based
on <code>git</code>, but I recommend against it. It's based on automatically
committing every <i>x</i> seconds, so you never exactly know if your latest
changes are already committed, and you end up with a very messy history of
partial and/or unrelated changes going into individual commits.
</p>

<h4> Mobile app </h4>
<p>
There is a functional mobile app, with the same look and most of the same
features as the desktop application. It is missing plugins, so in particular, no
git plugin. <code>git</code> synchronization on Android is still possible with
Termux, but less convenient than on a desktop, since it requires you to manually
go into Termux to commit/push/pull changes (and be very careful of ending up
with a merge conflict on your phone, that's much less fun to deal with on a
phone screen than in your favorite desktop editor).
</p>

<h4> Other features </h4>

Some other features include:

<ul>
  <li>
    Aliases: you can create aliases for tags, so that when you tag a note with
    any of the aliases, it will still point to the original tag. For example, if
    you have a tag "book", and add an alias "books", you won't have to remember
    if the tag was in the singular or plural.
  </li>
  <li>
    To-do lists.
  </li>
  <li>
    Scripting/queries: this is a feature I haven't looked into much yet, but it
    sounds very useful. You can write queries in a very general syntax to find
    notes that satisfy particular conditions. E.g. find all articles (tagged
    with <code>#article</code>) that are about graph theory (tagged with
    <code>#[[graph theory]]</code>) published in the last year (a date property
    is within a particular time frame).
  </li>
  <li>
    Embedding blocks: a bullet point (with everything nested below it) can be
    directly embedded elsewhere (such that editing either instance changes
    both).
  <li>
    Whiteboards.
  </li>
  <li>
    <i>The Graph</i>: a visualization of links/relationships between your pages.
  </li>
  <li>
    Flash cards.
  </li>
</ul>

<p>
The first two I use regularly. Queries I want to eventually get into. The others
I don't really find use for.
</p>

<h3> Problems </h3>
<p>
There are a few things I'm personally not a fan of with LogSeq.
</p>

<h4> Bloat </h4>
<p>
The biggest general problem for me is that despite a nice, minimal interface,
LogSeq is an Electron application. The <code>logseq-desktop-bin</code> AUR
package is <i>500MB</i>! All for a note taking application. In addition to the
bloat coming from Electron, I think a lot of it is also features that I have
absolutely no use for (like the aforementioned graph view and whiteboards, which
go way beyond basic text editing and markup).
</p>

<p>
Many people these days brush bloat under the rug, saying that on modern machines
it doesn't matter, and frameworks like Electron are good because it means
faster, simpler development. But these problems do end up having consequences.
For example, LogSeq struggles with large files.
</p>

<p>
The full text of Shakespeare's <i>Othello</i> (around 160KB) takes several
seconds to load, and the app displays a bright orange warning message that
"Large blocks will not be editable or searchable to not slow down the app."
<code>vim</code> opens the same file in a fraction of a second, a web browser
takes maybe about a second.
</p>

<h4> Not exactly MarkDown </h4>
<p>
The LogSeq team say that the underlying text files are just MarkDown, but that's
not exactly true.
</p>

<p>
The notes have to be all organized into bullet points, you don't have plain
paragraphs or headings. Furthermore, additional markup is inserted, e.g. for
block references. All of that makes the text less human-readable/-editable, a
core feature of MarkDown.
</p>

<p>
Which leads to the next very sad problem...
</p>

<h4> It's not <code>vim</code> </h4>
<p>
Once you get used to <code>vim</code>, all other text editing options are just
inferior. Bram's gift to humanity is both a blessing and a curse, since there's
no getting away from sometimes needing to edit text outside of it.
</p>

<p>
Yes, there's a "vim" plugin that implements some keybindings, but I tend to stay
away from those, as they're always disappointing: they implement some of the
most basic keys, but others I'm used to relying on are not supported. So I'd
have to remember which plugin for which piece of software implements which ones,
and it just becomes more of a hassle than a convenience.
</p>

<p>
As mentioned above, using <code>vim</code> directly on the text files is also
not a solution, since the notes format is not exactly standard MarkDown, and
either way you'd lose all the benefits of LogSeq, especially links/backlinks.
</p>

<h3> Conclusions </h3>
<p>
So, with that ranty section above over, what's my final verdict on LogSeq? I've
been using it daily for the past several months, and until something better
comes along, I don't plan on switching. Despite all its shortcomings, I really
like it, it helps me organize my notes and thoughts.
</p>

<p>
I was actually aware of Obsidian before, and it had piqued my interest, seemed
like a useful tool.  However, I didn't want to jump onto a proprietary
note taking solution. When doing my recent research on these apps, I found
LogSeq, which is a FOSS alternative. I was reluctant at first, for all the
reasons stated above, but after just a bit of test running, turns out the
benefits outweigh the trade-offs I have to make, and LogSeq has replaced
GitJournal for me.
</p>

<h4> The pipe dream </h4>
<p>
To finish this post, let me go on a little fantastical journey into what my
ideal note taking solution would look like.
</p>

<ul>
  <li>
    Given my <code>vim</code> addiction, it would be a <code>vim</code> plugin.
  </li>
  <li>
    Given my newly-found backlink addiction, the plugin would implement
    backlinking (e.g. displaying backlinks to a note in a separate pane, with
    links that can be followed VimWiki-style).
  </li>
  <li>
    Plain MarkDown syntax for notes.
  </li>
  <li>
    An easy-to-use query syntax.
  </li>
  <li>
    An Android application that supports backlinks, queries, and
    <code>git</code>.
  </li>
</ul>