Dynamic Note Content - banisterious/obsidian-charted-roots GitHub Wiki

Dynamic Note Content

Charted Roots can render live, computed content directly within notes using special code blocks. These blocks automatically display data from your vault and update when you view the note. Most blocks are designed for person notes, while some target other note types: Sources Block, Extractions Block, and Source Roles Block are intended for source notes, and the Members Block is intended for organization notes.

Table of Contents

Overview

Dynamic content blocks solve the problem of person notes containing only static frontmatter. With these blocks, you can see a person's complete timeline, family relationships, and more without leaving the note.

Key Features:

  • Live rendering: Content computed from your vault data
  • Freeze to markdown: Convert to static text for editing or export
  • Configurable: Options for sorting, filtering, and display
  • Multiple insertion methods: Command palette, context menu, import wizards

Block Types

Timeline Block

The canvas-roots-timeline block shows a chronological list of events for a person.

```canvas-roots-timeline
sort: chronological
```

What it displays:

  • Birth and death dates from the person's frontmatter
  • All event notes linked to this person
  • Age annotations on each event (when birth date is known)
  • Family member events β€” children's births, spouse deaths, parent deaths, sibling births (when enabled in Settings > Advanced > Family events on timelines)
  • Historical context events from an overlay note (when configured)
  • Year, event type, and place for each entry
  • Clickable wikilinks to event and place notes

Configuration options:

Option Values Description
sort chronological, reverse Event order (default: chronological)
include comma-separated types Only show these event types
exclude comma-separated types Hide these event types
limit number Maximum events to display
title string Custom header text (default: "Timeline")
context [Note](/banisterious/obsidian-charted-roots/wiki/Note), none Historical context note to overlay (see below)
contextMargin number Only show context events within N years of the person's lifespan (overrides global setting)
familyEvents none Suppress family member events on this timeline (overrides global toggles)
layout chronological, grouped, personal-first How events are arranged (see Layout modes)
format format string Custom display format with placeholders (see Format strings)
template [Note](/banisterious/obsidian-charted-roots/wiki/Note) Reference a template note defining custom sections (see Template notes)

Example with options:

```canvas-roots-timeline
sort: reverse
exclude: residence, occupation
limit: 10
title: Key Life Events
```

Historical context overlay

You can overlay historical events alongside a person's life events by referencing a context note. This helps understand what was happening in the world around them β€” wars, pandemics, economic events β€” and why ancestors may have made certain decisions.

Context note format: Create a markdown note with date-prefixed list items:

- 1861-1865: American Civil War
- 1914: World War I begins
- 1929-10-29: Black Tuesday
- 1941-1945: World War II

Dates can be a single year (1914), a year range (1861-1865), or a full date (1929-10-29).

Usage: Reference the note in your timeline block:

```charted-roots-timeline
context: [US History](/banisterious/obsidian-charted-roots/wiki/US-History)
```

To suppress the default context on a specific block, use context: none.

Filtering: By default, all context events are shown (contextLifespanMargin: 0). Set a margin in Settings > Advanced > Context lifespan margin to limit context events to within N years of the person's own lifespan. The margin uses only the person's own events (birth, death, etc.) β€” family events like sibling births do not expand the range.

Default setting: Rather than adding context: to every timeline block, you can set a default context note in Settings > Advanced > Default timeline context. All timelines will use this note unless overridden per block.

Age annotations

When a person's birth date is known, all timeline events (including context events) display an age annotation showing the person's age at the time of the event. For example, a marriage in 1875 for someone born in 1850 would show "age 25".

Timeline layout modes

The layout parameter (or the global setting in Settings > Advanced > Timeline layout) controls how events are arranged:

Mode Description
chronological (default) All events interleaved by date
grouped Separate sections with dividers: Life events, Family events, Historical context
personal-first Personal events first (sorted), then family and context events chronologically

Timeline format strings

The format parameter controls how each entry is rendered using placeholders:

```charted-roots-timeline
format: "{year} β€” {title} in {place}"
```

Available placeholders:

Placeholder Description Example
{year} Year or date range 1850
{date} Full date 1850-01-01
{type} Event type label Birth
{title} Event title/description Born or Birth of John
{place} Place name (omitted if empty) Boston, MA
{age} Age annotation (omitted if unknown) age 23

When a placeholder's value is empty, it and surrounding literal text (like "in ") are automatically omitted.

Timeline template notes

For full control, reference a template note that defines custom sections with independent configuration:

```charted-roots-timeline
template: [My Timeline Template](/banisterious/obsidian-charted-roots/wiki/My-Timeline-Template)
```

Template note format:

A template note uses ## headings for sections, each with optional sort:, include:, and format: config lines:

---
cr_type: timeline_template
---

## Life events
sort: chronological
include: birth, death, marriage, occupation
format: "{year} β€” {title} in {place}"

## Family
sort: chronological
include: family
format: "{year} β€” {title}"

## Historical context
sort: chronological
include: context

Include filter values: Event types (birth, death, marriage, etc.) and categories (personal, family, context, children_births, spouse_deaths, parent_deaths, sibling_births).

Set a global default template in Settings > Advanced > Default timeline template to apply it to all timelines without editing individual notes.

Relationships Block

The canvas-roots-relationships block displays family members with clickable links.

```canvas-roots-relationships
type: immediate
```

What it displays:

  • Parents (father, mother, adoptive father, adoptive mother, step-parents)
  • Spouse(s)
  • Children
  • Siblings (when using type: extended or type: all) β€” biological siblings share a parent with the focal person; adoptive siblings (other children of the focal person's adoptive parents) appear under the same Siblings heading with an Adoptive sibling: label, matching the labeling convention used for adoptive parents

Each person is shown as a wikilink with their birth-death years.

Configuration options:

Option Values Description
type immediate, extended, all Relationship scope (default: immediate)
include comma-separated types Only show these relationship types
exclude comma-separated types Hide these relationship types
title string Custom header text (default: "Family")

Relationship types:

  • immediate: Parents (biological, adoptive, step-), spouse(s), children. No siblings.
  • extended: Everything in immediate, plus siblings β€” biological (derived from shared parents) and adoptive (derived from shared adoptive parents, labeled Adoptive sibling:).
  • all: Everything in extended, plus custom-typed relationships declared in the person's relationships frontmatter array (mentor, godparent, ally, etc.).

2nd-degree kinship β€” aunts, uncles, cousins, grandparents, grandchildren β€” is not currently derived in any mode; see #424 for the tracked enhancement.

Example with options:

```canvas-roots-relationships
type: extended
title: Family Tree
```

Media Block

The canvas-roots-media block displays a gallery of media files linked to the person.

```canvas-roots-media
columns: 3
size: medium
```

What it displays:

  • All media files linked via the media frontmatter property
  • Image thumbnails in a responsive grid
  • PDF first-page thumbnail previews (generated via Obsidian's built-in PDF.js)
  • Document placeholders for other non-image files
  • First item highlighted as the "thumbnail" (used for Family Chart avatars)

Configuration options:

Option Values Description
columns 2-6, auto Number of columns in grid (default: 3)
size small, medium, large Thumbnail size (default: medium)
editable true, false Enable drag-to-reorder (default: false)
title string Custom header text (default: "Media")

Example with options:

```canvas-roots-media
columns: 4
size: large
editable: true
title: Photos & Documents
```

Editable Mode:

When editable: true is set:

  • Items show a drag handle on hover
  • Drag items to reorder their position
  • First item becomes the thumbnail (shown on Family Chart nodes)
  • Frontmatter is updated automatically when you drop
  • Gallery has a dashed border to indicate edit mode

Source Roles Block

The charted-roots-source-roles block displays a table of people and their roles in a source document.

```charted-roots-source-roles
source: "[Estate Inventory of John Smith Sr.](/banisterious/obsidian-charted-roots/wiki/Estate-Inventory-of-John-Smith-Sr.)"
```

What it displays:

  • All people listed in the source's role properties (principals, witnesses, informants, etc.)
  • Role category and label for each person
  • Role details (e.g., "Decedent", "Administrator") when present
  • Clickable wikilinks to person notes

Configuration options:

Option Values Description
source wikilink Source note to display roles from (default: current note)

Rendered output:

Role Person Details
Principal John Smith Sr. Decedent
Official Thomas Brown Administrator
Enslaved Individual Mary β€”

Inserting the block:

  1. Context menu: Right-click on a source note and select Charted Roots > Add source roles block
  2. Manual: Add the code block to any note, specifying the source

When inserted via context menu, the source parameter is pre-filled with the current note's wikilink.

Note: This block is designed for source notes (cr_type: source) that have role properties defined. See Person Roles in Sources for details on setting up role properties.

Transfers Block

The charted-roots-transfers block displays a chronological list of transfer events for a person. This is useful for tracking ownership changes in genealogical research (e.g., enslaved ancestor tracking) or succession in worldbuilding.

```charted-roots-transfers
sort: chronological
```

What it displays:

  • All transfer events linked to this person
  • Transfer type (inheritance, purchase, gift, hire, seizure, birth, relocation)
  • Date and event title with clickable wikilink
  • Location (if recorded)
  • Other participants in the transfer

Configuration options:

Option Values Description
sort chronological, reverse Event order (default: chronological)
limit number Maximum events to display
title string Custom header text (default: "Transfer history")

Example with options:

```charted-roots-transfers
sort: reverse
limit: 10
title: Ownership history
```

Transfer types:

Type Label Description
inheritance Inherited Transfer at death via will/probate
purchase Purchased Sale transaction
gift Gift Transfer without payment
hire Hired out Temporary transfer (hiring out)
seizure Seized Court-ordered transfer, debt collection
birth Born into Born into ownership
relocation Relocated Move to different location (same owner)

Use cases:

  • Genealogical research: Track enslaved ancestors through ownership chains, estate divisions, and probate records
  • Worldbuilding: Track succession of titles, thrones, and positions

Related: Transfer events require creating event notes with event_type: transfer and transfer_type property. See Events & Timelines for details on creating transfer events.

Members Block

The charted-roots-members block displays the members of an organization, grouped by role. Place this block in an organization note to see all persons who are members.

```charted-roots-members
group-by: role
```

What it displays:

  • All persons with a membership linking them to this organization
  • Members grouped by role, with clickable wikilinks to person notes
  • Date ranges for membership periods (e.g., "1850–1865" or "1920–present")
  • Former members shown with a dimmed style
  • Optional membership notes

Configuration options:

Option Values Description
group-by role, none Group members by role (default: role)
sort name, date Sort order within groups (default: name)
show-former true, false Include former members (default: true)
show-dates true, false Show membership date ranges (default: true)
show-notes true, false Show membership notes (default: false)
role-order comma-separated roles Pin specific roles to the top in order
title string Custom header text (default: "Members")

Example with options:

```charted-roots-members
group-by: role
sort: date
show-notes: true
role-order: Pastor, Elder, Deacon
title: Congregation
```

Rendered output:

When grouped by role, each role gets its own heading:

Pastor

Elder

Members

Role ordering fallback chain:

  1. Block-level role-order β€” if specified, those roles appear first in that sequence
  2. Organization's roles property β€” if the organization note defines a roles list, that order is used
  3. Alphabetical β€” remaining named roles follow alphabetically; members with no role appear last under "Members"

This means if your organization note already defines roles, the members block will use that order automatically without needing role-order config.

Note: This block is designed for organization notes (cr_type: organization). Membership data is stored on person notes via the organizations frontmatter property. See Organizations for details on setting up organizations and memberships.

Sources Block

The charted-roots-sources block displays a table of sources linked to a person note. It shows each source's type, title, date, and which facts the source supports.

```charted-roots-sources
sort: chronological
```

What it displays:

  • All sources linked via the sources frontmatter array
  • Sources referenced by sourced_* properties (fact-level citations)
  • Legacy sourced_facts entries
  • Source type icon, title as a clickable wikilink, date, and fact labels

Configuration options:

Option Values Description
sort chronological, reverse, type Sort order (default: chronological)
filter comma-separated types Only show these source types
exclude comma-separated types Hide these source types
title string Custom header text (default: "Sources")

Example with options:

```charted-roots-sources
sort: type
filter: census, vital_record
title: Census & Vital Records
```

Rendered output:

Type Title Date Facts
πŸ“‹ 1850 Census - Smith Family 1850 Name, Birth date, Residence
πŸ“œ Birth Certificate - John Smith 1845 Name, Birth date, Birth place

Fact-level citations:

When a source is linked via a sourced_* property (e.g., sourced_birth_date), the Facts column shows which specific facts cite that source. This gives a clear picture of what evidence each source provides for the person.

Note: This block is designed for person notes (cr_type: person). See Evidence & Sources for details on linking sources to persons.

Extractions Block

The charted-roots-extractions block is the inverse of the Sources block β€” it renders a reverse lookup from a source note to all entities that cite it. Place this block in a source note to answer the question "what have I extracted from this source?"

```charted-roots-extractions
title: Extractions
```

What it displays:

Three grouped sections, each with a count in its heading:

  1. Persons β€” All person notes that reference this source via sources, sourced_*, or legacy sourced_facts properties. Shows which facts each person cites this source for.
  2. Events β€” All event notes that include this source in their sources array, sorted chronologically. Shows event type, title, date, person(s), and place.
  3. Places β€” Unique places derived from the citing events, with a count of how many events reference each place.

Configuration options:

Option Values Description
title string Custom header text (default: "Extractions")

Rendered output:

Persons (3)

Name Facts cited
John Smith Name, Birth date
Jane Smith Name, Marriage date
Mary Smith Name

Events (2)

Type Title Date Person(s) Place
πŸŽ‚ [Birth of John Smith]] ](/banisterious/obsidian-charted-roots/wiki/1845-03-15- -[[John-Smith) Dublin, Ireland
πŸ’’ [Marriage of John and Jane]] ](/banisterious/obsidian-charted-roots/wiki/1867-06-20- -[John-Smith), [Jane Smith]]

Places (2)

Place Events
Boston, MA 1
Dublin, Ireland 1

Sections with no data are omitted. If no entities reference the source at all, an empty state message is shown.

Note: This block is designed for source notes (cr_type: source). It complements the Sources block on person notes by providing the reverse perspective. See Evidence & Sources for details on the source citation model.

Negative Findings Block

The charted-roots-negative-findings block displays a log of negative research findings β€” sources searched that did not yield results for a person.

```charted-roots-negative-findings
sort: chronological
```

What it displays:

  • All negative findings logged for the person from research journal entries
  • Date searched, source name, what was searched for, and notes
  • Helps identify which sources have already been exhausted

See Research Workflow for details on logging negative findings.

Research Timeline Block

The charted-roots-research-timeline block visualizes research activity across your vault with three view modes.

```charted-roots-research-timeline
view: table
person: "[John Smith](/banisterious/obsidian-charted-roots/wiki/John-Smith)"
```

View modes:

Table view (default)

A chronological activity log showing all research sessions:

Column Description
Date When the research was conducted
Source Source searched
Searched for What was being looked for
Result Positive, negative, or inconclusive (with icon)
Project Associated research project
Person Person the research relates to
Gap Days since last research activity (flagged if exceeding threshold)

Rows exceeding the gap threshold are highlighted in orange to draw attention to periods of inactivity.

Heatmap view

A GitHub-style contribution grid showing 52 weeks of research activity density. Color intensity indicates the number of research sessions per day. Includes a summary showing the longest gap period.

```charted-roots-research-timeline
view: heatmap
```

Timeline view

Horizontal bars per person or project with color-coded markers:

  • Green: Positive result
  • Red: Negative result
  • Yellow: Inconclusive result

Gap regions between markers are highlighted to show periods of inactivity.

```charted-roots-research-timeline
view: timeline
```

Configuration options:

Option Values Description
view table, heatmap, timeline Visualization mode (default: table)
person wikilink Filter to a specific person
project string Filter to a specific research project
gap number Minimum days to flag as a gap (default: 30)
sort chronological, reverse Sort order (default: chronological)
group person, project, source Group rows by field (table view only)
title string Custom header text

Data sources: Gathers entries from both research_log_entry frontmatter and research_journal markdown entries. Re-renders live when vault metadata changes. The table view supports freeze-to-markdown.

Universe Entity Blocks

Four blocks for universe notes that automatically list all entities belonging to that universe. Place these in a universe note.

charted-roots-universe-people β€” Table of people with name, born, died, occupation:

```charted-roots-universe-people
sort: name
limit: 50
```

charted-roots-universe-places β€” Table of places with name and place type.

charted-roots-universe-events β€” Table of events with name, date, type badge, and place.

charted-roots-universe-organizations β€” Table of organizations with name and type.

charted-roots-universe-maps β€” Clickable map image thumbnails for custom maps. Shows place count badge. Supports size parameter (small/medium/large).

All entries are clickable wikilinks. Supports sort (name/date/type) and limit parameters. Auto-refreshes when vault data changes.

Rendered Output

In reading view, code blocks render as styled containers:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Timeline                               [❄️] β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚ β€’ 1845 β€” Born in [Dublin, Ireland](/banisterious/obsidian-charted-roots/wiki/Dublin,-Ireland)        β”‚
β”‚ β€’ 1867 β€” Married [Jane Smith](/banisterious/obsidian-charted-roots/wiki/Jane-Smith)             β”‚
β”‚ β€’ 1890 β€” Resided in [Boston, MA](/banisterious/obsidian-charted-roots/wiki/Boston,-MA)          β”‚
β”‚ β€’ 1912 β€” Died in [Boston, MA](/banisterious/obsidian-charted-roots/wiki/Boston,-MA)             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Toolbar buttons:

  • ❄️ Freeze: Convert to static markdown
  • πŸ“‹ Copy: Copy timeline text to clipboard (timeline only)

Empty states:

  • If no data is found, blocks show a helpful message
  • Example: "No events found for this person"

Freeze to Markdown

Click the ❄️ freeze button to convert a live block to static markdown. This is useful for:

  • Manual editing: Add notes, reorder items, customize formatting
  • Export compatibility: Static markdown works everywhere
  • Performance: Reduce computation in large vaults

Before freezing:

```canvas-roots-timeline
sort: chronological
```

After freezing:

## Timeline

- **1845** β€” Born in [Dublin, Ireland](/banisterious/obsidian-charted-roots/wiki/Dublin,-Ireland)
- **1867** β€” [Marriage of John and Jane](/banisterious/obsidian-charted-roots/wiki/Married) in [Boston, MA](/banisterious/obsidian-charted-roots/wiki/Boston,-MA)
- **1912** β€” Died in [Boston, MA](/banisterious/obsidian-charted-roots/wiki/Boston,-MA)

The frozen content preserves wikilinks and can be edited like any markdown.

Media gallery freeze:

Media galleries freeze to a styled callout that displays images in a responsive grid:

> [!info|cr-frozen-gallery]
> ![portrait.jpg](/banisterious/obsidian-charted-roots/wiki/portrait.jpg)
> ![wedding-photo.jpg](/banisterious/obsidian-charted-roots/wiki/wedding-photo.jpg)
> ![birth-certificate.pdf](/banisterious/obsidian-charted-roots/wiki/birth-certificate.pdf)

The frozen gallery:

  • Uses Obsidian's native callout syntax with a special cr-frozen-gallery metadata tag
  • Renders images in a flex layout with configurable styling
  • Click-and-hold on an image to zoom to full screen
  • Styling can be customized via the Style Settings plugin

Inserting Blocks

Create Person Modal

When creating a new person note via the Create Person modal, enable the "Include dynamic blocks" toggle to automatically add timeline, relationships, and media blocks to the note body.

Import Wizards

All import wizards (GEDCOM, Gramps, CSV) include an "Include dynamic blocks" toggle. When enabled, imported person notes will include all three block types. Media blocks are included with editable: true by default.

Context Menu

Right-click on a person note in the file explorer:

  1. Select Insert dynamic blocks
  2. Timeline, relationships, and media blocks are added to the note body

Bulk Insert (Folders)

Right-click on a folder containing person notes:

  1. Select Insert dynamic blocks in folder
  2. A progress modal shows the operation
  3. Blocks are added to all person notes in the folder that don't already have them

Command Palette

Use the command palette (Ctrl/Cmd + P):

  • Charted Roots: Insert dynamic blocks - Adds blocks to the current note

Manual Entry

Type the code block syntax directly in any person note:

```canvas-roots-timeline
```

```canvas-roots-relationships
```

Tips

  • Placement: Add blocks after your frontmatter and any static content you want to keep at the top
  • Multiple blocks: You can have both timeline and relationships blocks in the same note
  • Re-ordering: Frozen content can be moved anywhere in the note
  • Performance: For large vaults (1000+ people), consider using frozen blocks to avoid computation on every note open
  • cr_id required: Blocks only work in notes with a valid cr_id property

Related Features