Logseq graphs and Obsidian vaults
Table of Contents
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.