ExcaliBrain

Structured relationship maps for notes, modelled on ExcaliBrain by Zsolt Viczián.

日本語

Overview

excaliBrain() renders each note in a planar layout with seven regions:

Relationships come from ExcaliBrain's ontology: YAML frontmatter fields and dataview inline fields in the note body. When a relationship is not stated explicitly, it is inferred from the content graph.

Usage

import { defineConfig } from "@riebeckite/core";
import { excaliBrain } from "@riebeckite/plugin-excalibrain";
 
export default defineConfig({
  // ...
  plugins: [
    excaliBrain({
      render: "build",
    }),
  ],
});

The plugin runs with order: -10.

Declaring relationships

Explicit relations win over inferred ones.

YAML frontmatter

---
title: ExcaliBrain Center
parent: "[[excalibrain-parent]]"
children: ["[[excalibrain-child-a]]", "[[excalibrain-child-b]]"]
---

Dataview inline fields

children:: [[excalibrain-child]]
 
related:: [[note-a]] and [[note-b]] are similar

An inline field may appear on its own line or inside brackets ([field:: [[target]]]).

Ontology

Field names are matched case-insensitively and spaces are normalized to hyphens. The default ontology is:

The ontology option extends the defaults: each role's field names are appended to that role's defaults rather than replacing them. An override can still add an existing field to another role, but earlier roles in the canonical order (parents, children, leftFriends, rightFriends, previous, next, hidden) win when a field is listed twice.

hidden follows ExcaliBrain: it lists the targets to hide from this note's map; it never hides the note itself. showHidden reveals those targets.

Inference

When infer is enabled (the default):

• a forward link (this note → other) becomes a child;
• a backlink (other → this note) becomes a parent;
• a mutual link (this note ↔ other) becomes a leftFriend.

With siblings enabled (the default), the other children of this note's parents become sibling nodes. Sibling inference also requires infer: setting infer: false disables it. Link targets are resolved against the content manifest; unresolved targets become virtual nodes labelled with the raw link text (data-node-virtual="true").

Publication boundary

Nodes are resolved against the content manifest. A target whose publishing.routable flag is false is dropped from the map, so notes excluded from publication never appear as nodes or links and their titles and permalinks are not leaked.

Rendering

The render option selects where the map is produced:

Injection

• A ```excalibrain fence is replaced by the map.
• Otherwise, when auto is enabled and the note has at least one relationship, the map section is appended to the article HTML (both the manifest entry and the cached post content).

heading / headingText control the optional <h2>.

Options

Output

<section class="rb-excalibrain" data-excalibrain
         data-excalibrain-render="build"
         data-excalibrain-center="notes/center">
  <h2 class="rb-excalibrain__heading">ExcaliBrain</h2>
  <div class="rb-excalibrain__canvas">
    <svg class="rb-excalibrain__svg" viewBox="0 0 720 480" role="img">…</svg>
  </div>
</section>

Each region is a g.rb-excalibrain__region[data-region]; each node is a g.rb-excalibrain__node[data-node-role][data-node-slug][data-relation-type] wrapping an <a href> around its <rect> and <text>. Links are path.rb-excalibrain__link[data-link-role][data-relation-type].

Limitations

• The map is read-only. The client layer only builds the SVG; there is no drag, zoom, or expand/collapse interaction.
• maxPerRegion truncates each region, so a note with more relations than the limit shows only the first nodes.
• Rendering is limited to the ontology roles above; there is no per-node styling or per-region configuration beyond the options listed below.

Exports

• excaliBrain(options?) / excaliBrainPlugin — plugin factory
• resolveExcaliBrainOptions(options?) — resolved defaults
• buildExcaliBrainGraph(input) — pure graph builder
• layoutExcaliBrain(graph, options?) — pure deterministic layout
• renderExcaliBrainSvg(graph, layout, options?) — pure SVG renderer
• Types: ExcaliBrainOptions, ExcaliBrainGraph, ExcaliBrainNode, ExcaliBrainLink, ExcaliBrainLayout, ExcaliBrainRole, ExcaliBrainRenderMode, …

See also

• Plugin guide