Overview

Dialog notes let you attach a decision, question, or comment to a specific passage, so the reasoning behind your work lives next to the work itself instead of in a lost chat thread. They are designed to be discoverable rather than memorized: you see where context exists, and read it on demand.

A note is nothing exotic: it is an ordinary org footnote whose label starts with a prefix (default note-). The reference [fn:note-why-db] marks the passage; the body is a footnote definition collected under a * Notes section. Because notes are real footnotes, they reuse all of org's footnote machinery (reference/definition jump, hover, and the lint that detects a footnote whose passage or body was deleted). The one thing that makes them special is that they are excluded from export: notes are meta, not document content.

Important subtlety: the prefix is the only thing that distinguishes a note from an ordinary footnote. A footnote is treated as a note (and excluded from export) only when its label starts with the prefix. Your normal footnotes are never affected:

In other words, this feature does not change how footnotes work in general; it only adds special treatment for the small, opt-in set of footnotes you mark with the prefix. The prefix is configurable with scimax.org.notes.labelPrefix (set it to, say, kb- and [fn:kb-...] becomes the note namespace instead).

What a note looks like

In the file, everything is plain text in one document:

* Storage layer
We store everything in an embedded database[fn:note-why-db] to avoid a
server dependency.

* Notes                                                          :noexport:
[fn:note-why-db] Decision · jkitchin · 2026-06-28 · open
  Chose embedded over client/server to keep zero-config setup.
  - reply (alice): revisit if we need multi-writer.

• The inline [fn:note-why-db] marker is the anchor; it travels with the passage when you move it and orphans (a lint warning) if the passage is deleted.

• The * Notes section is tagged :noexport: and collects the bodies, like a * Footnotes section.

• The first body line is a light convention, Type · author · date · state, parsed for display. Everything after is freeform (including replies).

In the editor

The marker stays visible (it is ordinary footnote syntax), so notes read naturally in plain text and in any other org editor.

Adding a note

1. Select the passage the note is about.

2. Run Scimax: Add Note (Decision/Question) on Selection (scimax.org.addNote), from the editor right-click menu or the Command Palette.

3. Pick a type: Note, Decision, or Question.

4. Type the body.

scimax inserts [fn:note-<slug>] after the selection (the slug is derived from the passage and disambiguated automatically) and appends the definition under * Notes, creating that :noexport: section if it does not exist. The author is your scimax.org.notes.author setting, or your OS username.

Notes and export

By default notes never appear in exported documents. When you export to HTML, PDF (LaTeX/Beamer), DOCX, or a notebook, only footnotes whose label starts with the notes prefix ([fn:note-...]) are stripped before rendering. Every other footnote, such as [fn:1] or [fn:methods], is left completely untouched and exports as a normal footnote. The exclusion is purely a label-prefix opt-in, not a blanket change to footnote export. Set scimax.org.notes.excludeFromExport to false if you want notes included in output too.

Orphan detection (free, via footnote lint)

Because notes are footnotes, the existing org-lint checkers already cover them:

• undefined-footnote-reference flags [fn:note-x] when its definition was deleted.

• unreferenced-footnote-definition flags a note body whose passage was deleted.

So a note whose target disappeared is surfaced automatically, with no separate machinery.

Settings

Related Topics

• Links - footnotes and link syntax

• Granular Addressing - anchors and back-links

• Export - export backends and options

• Commands - full command reference

• Configuration - all settings