The Kalem Book GitHub

This Book describes Kalem's main branch, which may be ahead of the latest release.

Logseq graphs and Obsidian vaults

The graph plugin of getkalem/plugins opens a Logseq graph or an Obsidian vault as itself: the folder of plain Markdown and Org files those applications keep, its pages, journals, links, block references, tags and tasks indexed, what links to a page shown beside it, the notes edited as an outliner. Nothing is converted: Logseq's logseq/ and Obsidian's .obsidian/ are never written, and both applications can go on reading the same files. The plugin is installed from the plugin list; its README and its work list (plugins/graph/graph_todo.md) are kept with it.

1. Which folders

A note belongs to a graph when its folder, or one above it, holds the application's marker:

Marker The graph
logseq/config.edn A Logseq graph (the file version)
.obsidian/ An Obsidian vault
mirror/markdown/.index.edn A Logseq database graph's Markdown Mirror

The setting graphs names folders that are graphs without a marker. The folder must be one of Kalem's projects: a plugin with fs:read:workspace reads the projects' folders and no others.

A Logseq graph is read as its config.edn sets it (format, workflow, folders, the journals' file and title formats, the file name format, hidden folders, the journal template, hidden and comma-separated properties, the favorites, what the graph view shows); a vault as .obsidian/daily-notes.json, app.json, templates.json, bookmarks.json and graph.json set it, read only, with the plugin's settings and then Obsidian's defaults behind them. The database version's own graph, a SQLite database, does not open; its Markdown Mirror, which Logseq writes from the database when it is turned on, opens as a Logseq graph that is never written.

2. The index

The plugin reads every note once, when a note of the graph is first opened or a command needs it, and then the file a save or a change on disk names: a save that keeps the page's names changes only that file's entries. Pages are named as each application names them (Logseq's titles, aliases and file names, journals by date; Obsidian's paths, the linking note's folder first and then the shortest path), and every reference is resolved: links, tags, block references, embeds, the pages a property names. A graph of a million blocks is indexed in about two seconds, for which the plugin asks Kalem for a viewer's limits, 1 GB and 10 s a call.

3. What it shows

  • The status bar names the graph of the current note and its pages; a click opens the graph's menu.
  • The graph's menu (SPC n r m, the Graph button, or that click), as Logseq's and Obsidian's left sidebar: the journals, today's journal, the graph drawn, all pages, tags, tasks and search, then the favorites, the pages opened last and the other graphs.
  • The graph drawn: Graph View, the pages as dots and the links as lines, and Local Graph, a page and the pages two links from it. Kalem lays them out and draws them, in the terminal too.
  • The backlinks panel: the page's linked references, grouped by page, then its unlinked references, searched for when they are opened, as Logseq does.
  • Documents, each written again when the graph changes, Enter on a line opening it: a page's backlinks, all pages (whiteboards and canvases apart, with the application that draws them), the journals, the tags, the tasks (NOW and DOING first, what is due within a week), the graph as a tree of namespaces with the pages named without a link and the orphans, and a query's results.

4. Keys

The plugin takes Doom Emacs's org-roam map, SPC n r, in the Vim profile, and adds to it; everything is in the palette, and most of it in the Graph menu.

Keys What it does
SPC n r m The graph's menu
SPC n r v, SPC n r V Graph View, Local Graph
SPC n r r, SPC n r R The backlinks panel, the backlinks document
SPC n r f, SPC n r i Find a page, insert a link to one
SPC n r b Insert a block reference
SPC n r o Follow the reference at the cursor
SPC o l in a note Open Link, the graph's references first
SPC n r d t, d y, d m Today's, yesterday's, tomorrow's journal
SPC n r d d, d f, d b The journal of a date, the next, the previous
Alt+], Alt+[ in a note The next journal, the previous
SPC n r p, j, T, t, g All pages, journals, tags, tasks, the graph
SPC n r q Run a query
SPC n r l, SPC n r a A page opened last, a page at random
SPC n r s Index the graph again
SPC n s, SPC n S In a graph: search its folder, find a heading

In a note of a graph, Doom's Org keys under SPC m edit it as an outliner: SPC m t (SPC m t t in Markdown, where SPC m t is Doom's toggles) cycles a block's task keyword as Logseq cycles it, SPC m p p sets its priority, SPC m d s and SPC m d d its SCHEDULED: and DEADLINE: (not in a vault, whose notes have neither), SPC m z (or Tab in normal mode, in Markdown) folds it: in a Logseq note in Markdown by writing collapsed:: true as Logseq does, elsewhere with Kalem's own fold; Alt+Shift+Up and Down move a block with the blocks under it, Alt+Shift+Right and Left (or Tab and Shift+Tab while typing in a Markdown list item) indent and outdent it. Enter while typing in a Logseq note in Markdown makes a block as Logseq's Enter does: after the block's properties, as its first child when its children are shown, splitting the block at the cursor. Each is one undo step. Rename Page rewrites every reference to the page in every file and renames the page's file (a Logseq page named by title:: keeps its file and gets a new title::); it refuses a journal and a name another page has. Block References lists what refers to the block at the cursor. In a Logseq graph in Org, Enter on a [[page]] in Vim's normal mode opens the page, not a heading of the file, and does what Org's Enter does elsewhere. In All pages, s sorts by title, by links or by blocks.

5. How a note is drawn

The note opens in Kalem's Markdown or Org mode, and the plugin's layer over the mode changes what Logseq and Obsidian show differently, away from the cursor:

Logseq Obsidian
id::, collapsed:: and the properties Logseq hides, hidden A line's ^id and %%comments%%, hidden
((uuid)) as its block's text A callout's [!note] as its icon and name
An embed as ↳ and its block or page, its blocks under it An embed as ↳ and its note or block
{{query …}}, #+BEGIN_QUERY: ⌕, the count, results under it  
Task keywords, priorities, dates and tags styled ==highlights== and tags styled
^^highlights^^ styled, numbered blocks as 1., a., I.  
#+BEGIN_NOTE and the other admonitions as icon and name  
:LOGBOOK: folded, a folded block's children hidden A callout with - folded

Show Source shows the file as it is. Wiki links are Kalem's own, in the core's Markdown mode.

6. Queries

Logseq's simple queries run over the index: pages and tags (as Logseq's path references count them), text, and, or, not, task, priority, between (a journal's day, SCHEDULED: or DEADLINE:), property, page-property, page-tags, page, namespace, sort-by and sample. Follow Reference on a query's line, or Run Query, opens its results grouped by page, or as the table query-table:: and query-properties:: ask for; t on a line cycles its task's keyword in its file. Advanced queries (#+BEGIN_QUERY, Datalog) run too, as Logseq's file version runs them, over the same schema; Clojure of one's own (:result-transform, :view) is not run, and the query says so.

7. What it writes

With fs:write:workspace, only what the user asks for: a new journal from the graph's template when no file is there, a block's id:: when it is first referred to, the references to a renamed page and its file renamed (moved, never deleted), a task's keyword cycled from the Tasks or a Query document. Each file is read again just before, only the lines concerned change, and a file Kalem holds with unsaved changes is never written. Nothing under logseq/ or .obsidian/, and nothing in a Markdown Mirror.

8. From the command line

kalem run prints the documents:

kalem run graph graph.pages ~/notes
kalem run graph graph.backlinksDocument ~/notes/pages/Kalem.md

9. What it does not do

Whiteboards and canvases are drawn, read only: following one shows its shapes where Logseq or Obsidian places them (Kalem 0.6.27 and later), to be changed in its application. The applications' plugins and their syntax (but Dataview's inline fields), PDF highlights drawn over the PDF and real-time sync are not there; a graph synced with Syncthing or git goes on being so.