Block references

Block references are links to a block of a text note, such as a paragraph, a heading, a list item or a table, or to a range of consecutive blocks. A block reference can be pasted in another note as a link, or turned into an Include Note that shows only the referenced blocks.

Copying a reference

  1. Place the cursor in the block to reference. To reference several consecutive blocks, select them.
  2. Right-click the block handle, the sequence of dots to the left of the block (see Formatting toolbar), and select Copy reference. With the fixed formatting toolbar, clicking the block handle opens the same menu. Alternatively, right-click the text and select Copy reference to this block in the Copy submenu, or Copy reference to these blocks for a selection. The referenced blocks flash briefly.
  3. Go to the note where to insert the link and press Ctrl+V.

Inside a Content tabs block, the reference points to the whole block. To link to a single tab, use Copy reference to this tab in the  More actions menu of the tabs block instead. Inside a Multicolumn layout, the reference points to the blocks in the column, and an include shows them without the layout around them.

The link shows the title of the note, followed by the beginning of the referenced text. A link to blocks of the same note shows only the beginning of the referenced text, and a link to a heading of the same note shows the whole heading.

If the note is shared, the menu of the block handle also offers Copy public link. It copies the web address of the shared page with the reference added, to send to people who read the note outside Trilium. Opening the address scrolls the shared page to the referenced blocks and flashes them. On a shared page, a link to blocks of another shared note does the same.

The Paste submenu of the context menu offers two more ways to insert a copied reference:

  • Paste reference as a link inserts only the link, even when the reference was copied as plain text or along with other content.
  • Paste reference as an excerpt inserts an include of the referenced blocks, as described below.

In a browser, the context menu of the text editor opens only when right-clicking selected text. Elsewhere the browser shows its own menu.

Linking to a heading

Since v0.107.0, a link to a heading of the same note can be created from the Add link dialog:

  • Place the cursor at the desired position of the link, or select the text to turn into a link.
  • Press Ctrl+K or the button in the Formatting toolbar, then select Heading / anchor at the top of the dialog. Alternatively, choose Link to a heading or anchor in the Slash Commands, which opens the dialog on that page.
  • Under Headings, click the desired heading to check it. Sub-headings are listed under their heading and start collapsed; expand or collapse a heading with the arrow in front of it, or with → and ← while it is focused. Optionally, type a Link title.
  • Press Enter or Insert link to confirm.

When the link title is not set, the link displays the text of the heading. If the heading gets changed, the link is renamed automatically to the new text, shortly after you stop typing. A link with a title of its own keeps that title.

The link is a block reference to the heading, so it keeps working when the heading is moved. To change the link, click it and press the Edit link button in its popup. For a link with a title of its own, placing the cursor inside it and pressing Ctrl+K works too. The dialog opens on Heading / anchor, with the heading checked. Emptying the Link title there makes the link display the text of the heading again.

Following a reference

Clicking a block reference opens the note, scrolls to the referenced blocks and flashes them. If a referenced block was deleted, an error message is shown instead, along with the blocks of the range that still exist.

A link to blocks of the note it is in, such as a link to a heading, scrolls to them and flashes them without leaving the note, as a link within a web page does. This works in read-only notes and on shared pages too. While editing, clicking the link shows its popup: press Jump to heading there, or Jump to block for other blocks.

Including the referenced blocks

To show the referenced blocks inside another note, right-click the link in a note being edited and select Convert link to note excerpt, or paste the copied reference with Paste → Paste reference as an excerpt. The include shows only the referenced blocks, not the rest of the note, and marks them with an Excerpt badge in its title. It starts at the Full box size, so all the referenced blocks are visible. To see the whole note, press the button in the same title, which opens the note in a new tab. Converting the include back to a link keeps the reference.

To edit the referenced blocks without leaving the note, press the Edit excerpt button in the title of the include, or turn on Editable () in its toolbar, as for any Include Note. Press the button again to stop editing. The changes are saved to the referenced blocks, and the rest of the note stays as it is. The button is grayed out where the blocks cannot be edited, such as in a read-only note. An excerpt has no Fullscreen button.

If a referenced block was deleted, the include shows Broken reference.

Limitations

  • References can be copied only from a note being edited, and not in the mobile layout.
  • An include of a range that covers only part of a list or a quote, such as from its second item to a paragraph after it, cannot be edited in place.
  • Deleting a block breaks the references to it.
  • Block references are not kept when exporting to Markdown. On a shared page, a block reference opens the whole note.