10 Blocks

Goals

Implement Roam like block references in Dendron.

Context

Block references let you link or embed blocks of text into different parts of your notes. This allows you to link and refer to any part of a note, including paragraphs, lists, and tables.

Lookup

This section describes existing work that has been done on this topic.

Proposal

Extend Dendron syntax to support block references. Obsidian has a great implementation of this already - unless there are critical deficiencies, we should adhere to their implementation and strive for interoperability.

Concepts

A block link has the following format. It is created in a note that is referencing a piece of text. When navigating the link, users should be taken to the block anchor.

[[somelink#^1234]]

Block Anchor

A block anchor is a ^ character, followed by one or more digits, letters, dashes, and underscores. Dendron should automatically generate these anchors when requested, and users should be able to add in custom anchors. The following are a few examples of anchors:

Lorem ipsum dolor amet ^1234

* Item 1
* Item 2 ^second-item
* Item 3

^whole-list

| Sapiente | accusamus |
|----------|-----------|
| Laborum  | libero    |
| Ullam    | optio     | ^whole-table

^whole-list, ^whole-table, and ^1234 reference the blocks they are attached to. Lists are special though, ^second-item only references the list item it is next to.

A block reference link is a reference to a block link.

![[somelink#^1234]]

Block Range References

Block references should also support range references (Private). Any valid block anchor is also a valid target for the start or end of a range.

When referring to block anchors, the range will be inclusive on both ends. For example:

paragraph 1

paragraph 2 ^start

paragraph 3 ^end

paragraph 4

![[#^start:^end]]

The reference here will include both paragraph 2 and 3. A single paragraph can be referenced without the range.

The range can also refer to anchors inside lists. When referencing lists, the anchors will include the list items between them.

* Item 1
* Item 2 ^start
* Item 3 ^end
* Item 4

![[#^start:^end]]

This references the items 2 and 3.

Details

  • to create a block, add #^{id} to the end of a wiki link (Private)
    [[filename#^1234]]
    
  • typing ^ will trigger a search of all blocks that currently exist within the file
  • inputting enter will generate a block anchor, a random id, in the target file
  • typing ^^ will trigger a search of all existing block anchors

Tasks

Example

  • link to block
Some notes ^dcf64c

[[#^dcf64c]]

More notes
  • html
<!-- source -->
<div id="dcf64c">
<a aria-hidden="true" href="#dcf64c"><span class="icon icon-link"></span></a>
<p> Some notes </p>
</div>

<a  href="...#^dcf64c">filename</a>

<div>
<p> More Notes </p>
</div>
  • link to block

    • file a
    Some notes ^dcf64c
    
    • file b
    [[filename#^dcf64c]]
    
    More notes
    
  • html

    • a.html
    <!-- source -->
    <div id="dcf64c">
    <a aria-hidden="true" href="#dcf64c"><span class="icon icon-link"></span></a>
    <p> Some notes </p>
    </div>
    
    • b.html
    <a  href="...#^dcf64c">filename</a>
    
    <p> More Notes </p>
    

Block reference to other file

  • link to block

    • file a
    Some notes ^dcf64c
    
    • file b
    ![[filename#^dcf64c]]
    
    More notes
    
  • html

    • a.html
    <!-- source -->
    <div id="dcf64c">
    <a aria-hidden="true" href="#dcf64c"><span class="icon icon-link"></span></a>
    <p> Some notes </p>
    </div>
    
    • b.html
    <p>Some notes</p>
    
    <p> More Notes </p>
    

Tradeoffs

  • we are using a purely plaintext based approach of doing block references which means that we are leaving artifacts in the source doc when we generate a block reference
    • alternatives are using a separate mapping file or using a db, the former adds a layer of indirection that doesn't fit with our current note modal, the latter is currently out of scope

Discussion


Children
  1. HTML Integration
  2. Markdown Integration
  3. Parsing Block Syntax
  4. Vscode Integration

Backlinks