References and indexes

References and academic indexes

Guide home · 简体中文

References and commands

Same note: [[#^thm-composition]]
Another note: [[Chapter One#^thm-composition]]
Custom label: [[Chapter One#^thm-composition|composition theorem]]
Markdown link: [composition theorem](Chapter%20One.md#^thm-composition)

Block IDs use letters, digits, and hyphens and must be unique within a note. Leave a blank line after the block and place ^id on its own line. For nested blocks, use the add-ID command to avoid assigning an ID to the wrong nesting level.

Open the command palette (Ctrl+P on Windows) and search for Academic Notes:

Action	Command label
Add a unique block ID at the cursor	Add a block ID to the current equation, theorem or figure
Select a target and insert its reference	Insert theorem, equation or figure reference
Rebuild the index and refresh references	Rebuild index and refresh references
Insert or reopen a commutative diagram	Insert or edit commutative diagram (Beta)
Export the current note as PDF	Export current note to PDF
Export the current note as HTML	Export current note to HTML snapshot
Select notes and export a book	Select notes and export a PDF book
Export a book from a manifest	Export phb-book manifest to PDF
Open diagnostics	Check plugin status and export environment

Type \ref, \tref, or \eqref for reference suggestions. The latter two filter to mathematical callouts or equations. Reading view and Live Preview replace reference labels; Source mode preserves the syntax. Moving the cursor into a reference in Live Preview also reveals its source. Custom aliases are preserved by default.

Numbering settings

Setting	Behavior
Reset at H2 headings (default)	Every source ## starts a new counter scope; H3–H6 do not reset it.
Include H2 section number	Displays 2.1 instead of 1; turning this off still allows section resets.
H2 number source	Use heading order, or prefer a leading number such as ## 3.2 Title.
Continuous numbering	Count throughout the note without H2 resets or section prefixes.
Shared theorem counter	Mathematical environments share a counter; equations, figures, and tables remain separate.
Number prefix	Set explicitly; no prefix is inferred from dates or filenames.
Excluded paths	One vault-relative file or directory per line.

With H2 headings, material before the first H2 belongs to section 0. If a note has no H2 headings, section numbers are omitted. Headings inside code, math, or comments do not start sections.

Equation references default to eq:{number}; mathematical callouts use {type} {number}. {type} follows the abbreviation setting, {abbr} is always abbreviated, and {name} is always the full name. {title} and {file} are also available. Figures and tables default to fig {number} and tab {number}.

Reference checks and academic index notes

Open the command palette and run Academic Notes: Check academic references. Choose the current note, its folder and subfolders, the entire indexed vault, or the current phb-book manifest. The checker finds missing target notes/blocks, ambiguous or duplicated IDs, manual-number conflicts within the same counter scope, and references outside a book. Ordinary Obsidian block links are accepted. An excluded target is reported as not checked, rather than a broken link. Filter results and use Go to location or Other occurrence to inspect the relevant source line. The checker does not modify notes.

Create academic index note creates a regular .md file with ordinary internal links. It works inside Obsidian and does not require PDF export or an enabled plugin to follow its links:

1. Choose the scope, destination path, environment types and grouping (by type or source note). Custom environments are included in the type selector.
2. Preview the list, then choose Create or update. Numbered and unnumbered entries can be included.
3. Open that index later and run Update current academic index note to regenerate it after edits. It is a saved list, not a continuously rewritten view.

Unique block IDs link directly to their environments. Entries without a unique ID link to the nearest heading or source note and are explicitly marked. Use the existing add-block-ID command on an environment to make its next index entry precise. Original notes are not rewritten in bulk. Index labels use the numbering visible in the vault, including when its scope is a book; PDF chapter renumbering is separate.

Only the region between academic-notes:index:start and academic-notes:index:end comments is updated. Keep your introduction and annotations outside those markers. Updating an ordinary note, a damaged index or an index with duplicate regions is refused. While the plugin is running, renaming or moving source notes/folders updates the embedded index configuration. A folder index keeps its folder scope when an individual source note moves elsewhere. Renames performed with the plugin disabled cannot be tracked retrospectively; regenerate the index if necessary. Obsidian can track the ordinary links in the list according to its normal link-update preference. Generated index links do not cause otherwise unreferenced equations to become numbered.

Referencing unlabelled targets

The reference picker and \ref / \tref / \eqref suggestions now include environments without a block ID. Add ID and insert reference creates one unique native ^an-… anchor on the selected target, then inserts the ordinary wikilink. It does not label the rest of the vault. Existing IDs are reused. Open unsaved buffers are respected; changed or ambiguous targets are rejected. If the origin changes during a cross-file write, the target ID is retained and you are asked to insert the reference again rather than overwrite your edits.

Generated indexes record their last generation time. Reading view shows whether the saved list matches the current indexed content and provides a refresh button. Contents still update only on request.

LaTeX equation references and row numbering

Rename maintenance and reference previews (2.15.5)

Maintain academic references after rename is enabled by default under Numbering and references. Renaming a Markdown note or folder updates LaTeX paths and phb-book.files, including relative outgoing paths when the source note moves. Native note-link renaming remains controlled by Obsidian. YAML comments, chapter titles and unrelated properties are retained. Disable this option if you prefer to manage these paths yourself.

Use Rename an academic label in the command palette, or Rename label in a preview. Choose a target, enter a new label, and select Preview changes. The preview lists affected notes and before/after lines. Apply changes updates the declaration plus wikilinks, Markdown links and LaTeX references; code examples and comments are excluded. Native IDs use letters, digits and hyphens; LaTeX-only labels also allow Unicode letters/digits, colons, dots and underscores. Duplicate names are rejected. Undo rename remains available in the same dialog if the affected content has not changed. Close and reopen the command to rename another target.

The operations inspect Markdown notes across the vault, including notes excluded from the normal numbering index. Open editor buffers take precedence. A stale preview is rejected; a mid-operation conflict rolls back completed writes when their contents still match, and reports any concurrently edited notes needing review.

Enable Reference preview under Numbering and references. On desktop, hover or focus on a rendered reference; Escape or the close button dismisses the card. On mobile, tap to preview, then choose Open target or Open in new tab. Desktop clicks and Ctrl/Cmd-click retain direct navigation. The preview lists incoming references from the current index (up to 50 locations). Theorem snippets are bounded; long equations and image/diagram targets can be opened in the note. Turning the option off restores direct mobile taps. Previewing does not modify Markdown.

Grouped reference suggestions (2.15.6)

Type \ref, \eqref or \tref to show suggestions. \ref searches all academic targets; \eqref filters equations and \tref filters theorem-like callouts. Start typing a title or label to search directly, or choose This file, a folder or a note to open the reference browser. This file appears when the current scope contains matching targets from the current note.

The browser keeps its own search field and path. Choose folders and notes with a click/tap or Enter; use Back or All notes to change scope. File names retain .md, so a note and a folder with the same name remain distinct. Escape or closing the window cancels without editing the note. Browsing does not create undo entries. Only selecting a final target replaces the original reference query. If the source note changes or its editor switches to another note while browsing, insertion is rejected before modifying a target.

Within a note, targets use document order by default. Enable Prefer manually numbered reference suggestions under Numbering and references to put manual numbers first; exact label matches remain ahead of incidental matches. The command-palette reference picker retains its existing flat search.

In $...$ and $$...$$, choosing an equation inserts \eqref{...} and other environments use \ref{...}. Prose uses ordinary wikilinks. Existing row labels and callout-title block IDs are preserved; ambiguous labels are rejected rather than silently selected.

Nested references and previews (2.15.7)

Labels inside nested callouts now target the owning environment, including title-line IDs. On desktop, plain hover in Live Preview shows the plugin card when native Page preview requires Ctrl/Cmd; modifier hover can use native preview. Nested theorem-family previews reconstruct their callout frame. Mobile tap-to-preview remains available.

In the reference-preview settings, the row-only multi-line equation preview option is enabled by default. A reference to a labelled row previews that row; disable the option to show the complete equation block. Unlabelled targets fall back to the whole block.