Logseq as "org-roam mobile"

Starting out, you'll note Logseq seems to put absolutely everything in a list. These lists are a lie. What you think is a list item is what they call a "block", which translates to Org jargon as a subtree.

This looks familiar only so long as you don't really have paragraph-text under your Org headings. If you do, you can hide the leading bullets by switching to "Document mode", and the result may feel more familiar.

To make sense of the Logseq UI, know that it's designed around the assumption you'll use subtrees extensively. This flies in the face of how I and many others write in Org-roam: many of my files have zero subtrees.

---

The above leads us to a small gotcha: Logseq expects headings. If the first logical line of text is not a heading, Logseq will still interpret it as a heading. So there's this odd leading bullet out of nowhere before the first paragraph. Think nothing of it; it's only cosmetic. Again, Document mode should hide it (sometimes it bugs and does not, so turn it off and back on).

(In fact, the bullet-out-of-nowhere happens even if the first paragraph is actually a set of properties such as #+TITLE, but you can hide them by putting into config.edn the line :block-hidden-properties #{:title}. Then you'll instead have an empty line at the top, which is there because of the file-level ID in your Org-roam files. Again, just cosmetic. A blank line isn't so bad.)

---

On the mobile app, we have buttons for manipulating subtrees: all the polished stuff you'd expect, like indenting and outdenting them, and moving them. These work only on subtrees! In fact, TODO state ends up being visually rendered as a checkbox when you're not editing, which tells you something about how they intend subtrees to be used.

You don't need to adopt the writing style presumed by Logseq, but it basically works like this: imagine that your initfiles include (setq org-startup-folded 'showeverything), and you eliminate the settings for the faces org-level-1 thru org-level-8 so that headings look just like the default face. Then you write lots and lots of headings, as if they were plain lists, and forget about regular plain lists. That's the expected style in a nutshell.

Bear in mind, Logseq will render conventional Org documents fairly sanely, so it works fine as a viewer. The discomfort arises when you want to edit inside Logseq and still stick to your non-Logseq norms: then you need to always keep in mind what you're doing to the underlying file. But I expect this becomes second nature after some time.

(defvar-local my-logseq-cookies nil)
(define-minor-mode my-logseq-mode
  "De-fontify Org headings."
  :group 'org
  (when (featurep 'org)
    (let ((headline-faces '(org-level-1
                            org-level-2
                            org-level-3
                            org-level-4
                            org-level-5
                            org-level-6
                            org-level-7
                            org-level-8)))
      (if my-logseq-mode
          (dolist (face headline-faces)
            (push (face-remap-add-relative face 'default) my-logseq-cookies))
        (while my-logseq-cookies
          (face-remap-remove-relative (pop my-logseq-cookies)))))))

There are two keys that can create a newline, with different effects (just like you have RET, M-RET, M-S-RET in org-mode). On the desktop Logseq app, they're Return and Shift+Return. The first is context-aware and very happy to create new subtrees, so as an org-roam writer you probably want to just avoid Return.

Before you ding the devs for this oddness, these keys are actually in line with convention for modern UI, in a way. Think of what you do in a chat app: if you want to send your chat message, you press Return. If you just want to make a newline without sending, you press Shift+Return. It's the same here.

However, on mobile it's the inverse. Chat apps have a dedicated Send button, so the onscreen keyboard's return key just prints a newline. In Logseq Mobile, it's instead the onscreen keyboard's return key that has magic behavior. The equivalent to polite old Shift+Return is present as a button just above the screen keyboard.

How to insert checkboxes in the app?

First, there's a long-unfixed bug (github.com/logseq/logseq/issues/3147). You'll have more success writing list bullets as + instead of the more conventional -.

+ [ ] i am a list item

Second, you have to type the first list-item manually, but after that, just enter newlines to autocreate more items.

Third, there are no indent/outdent commands for lists (only for subtrees). To make a sub-list, you have to manually prepend two spaces, but after that, you can once again enter newlines to autocreate new items at the correct indentation.

(It's telling that this is still better UX than any other Org app I've tried…)

Fourth, you'll sometimes see list items not being rendered as such. This isn't necessarily a bug, it can be that you tried to write a list item as the first text of a subtree… meaning you actually wrote a heading that happens to start with a dash character! Think logically about the underlying Org file.

For someone who only uses the mobile app (and not desktop Logseq), this feature is so non-discoverable I'm impressed. In short, you should know there's a bunch of commands you can call by typing a slash character (/) anywhere (yes, on mobile too), and some others by typing an opening angle bracket (<). You can even add new commands in config.edn. Do with that info what you will.

As far as I can tell, there's no way to stop this. Maybe by adding to config.edn this line?

:hidden ["/page/contents.org" "/page/favorites.org"]

Anyway, you can just cope with this by using them. They're magic files;

• what goes in contents.org also appears in the right-hand sidebar, and far as I can tell, it's meant as a sort of master index like Wikipedia's List of lists of lists;
• what goes in favorites.org appears in the left-hand sidebar as a favorites section.

Don't worry, these pages are imaginary. They don't exist as disk files until you write something in them.

The odd thing is that you enter the journal every time the app starts up, even if the journal is disabled…!

So it's not enough to put in config.edn this line:

:feature/enable-journals? false

You'll also want to set a homepage so it won't open the journals. Like this:

:default-home {:page "Contents"}