2. Get Started

1. Summary of Core Features

The Equation Citator plugin transforms Obsidian into a powerful academic writing environment with LaTeX-style citations. Making referencing in the vault easier than ever. It includes very rich features, including :

• Auto-numbering: Automatically number equations/figures, with all citations automatically updated.
• Rename tags : you can rename the tag of a specific equation/figures while keeping citations correct.
• Citations for Equation, figures and callouts: Tag and reference equations with \tag{} and \ref{}. use |fig:1.1| for figures, also supports citing tables/theorems by callouts. Use citations to preview and jump everywhere.
• Continuous Citations & Cross-file Citations: Reference multiple equations across multiple documents in a compact view.
• Auto-complete while citing : when writing \ref{} grammar, it auto-completes what you are looking for. Rich auto compete for figures/callouts are also supported.
• Figure captions : adding fig:1.1|title:|desc:description to figure metadata will automatically render them under figures.
• Manage panel for equations, figures and callouts : Full manage panel with list/outline view.
• Drag & Drop Citations : Drag equations from the management panel.
• PDF Export: Generate properly formatted documents for publishing
• Web note export (v1.3.5+): Sync the notes to a website-build folder.

Compatibility Typst Mate support (v1.3.1+): This plugin also support obsidian typst mate, you can set settings > Display (Categorical) > Others > enable typst mode make it compatible with typst syntax. Excalidraw support (v1.3.3+): Excalidraw figures can be cited just like fig: with correct preview

2. Basic Citations Grammar

We designed this plugin to be simple and easy-to use. Grammars of citations are summarized as following table. If you don’t need examples, You can check #1.4 Interactive Features and then jump directly to 3. Equation Manage Panel.

Citation Syntax Table of below

Feature	Syntax	Example
Equation Tag	\tag{label}	\tag{2.1}
Equation Cite	$\ref{eq:label}$	$\ref{eq:2.1}$
Figure		
Table	> [!table:label] Title	> [!table:3.1] Results
Cross-file	$\ref{eq:footnote^{label}}$	$\ref{eq:1^{2.3}}$
Multiple	$\ref{eq:1.1, 2.1}$	cite multiple equations
Continuous	$\ref{eq:1.1~3}$	Range notation

1.1 Creating and Citing Equations

Add a tag to any equation using \tag{label}:

To cite this equation, type \ref{eq:1.1} which renders as (1.1)

Quick Commands (use ctrl + p to search and add a hotkey to that😄!):

• Insert a citation in cursor position : Quickly insert \ref{}
• Insert equation citation on cursor position: Quickly insert \ref{eq:}
• Insert tag on cursor position with auto-number: Add tags with automatic numbering when cursor is in an equation block.

Auto-Complete Feature : just inserting \ref{eq:} and typing is much faster than dragging citations, since we support auto-complete for all types of citations.

For equations, just select what you want to insert in auto-complete panel.

Concise/Rich autocomplete mode: for figures and callouts, by default only tag and title will show. You can preview contents by hovering your mouse on option. Or you can use settings > citation > show full preview in autocomplete to show full picture/callout in autocomplete options.

You can only cite 1 type of either equation, figure or callout in a citation, such as $\ref{eq:1.1, 1.2}$ or $\ref{fig:1.1, 1.2}$, and it will take the begin from ref{ as the prefix to mark which type you cite. So mixed citation \ref{eq:1.1, fig:1.2, table:1.3} is not allowed.

1.2 Multiple / Continuous Citations

You can cite multiple equations with commas as $\ref{eq:1.1, 1.2, 1.3}$, rendered as (1.1~3)

Continuous Citations: This feature is enabled by default. The Continuous Citations combine citations and render them as (1.1~3). And we can also use \ref{eq:1.1~3} (1.1~3) as continuous citation grammar for multiple equations.

1.3 Cross-file Citations

The cross-file citation relies on the built-in footnote system of obsidian : so you can create footnote using following syntax :

[^1]: [[Document_A|Paper-A]]
[^2]: [[Document_B|Report-B]]

The cross-file citation syntax: $\ref{eq:footnote^{tag}}$. For example (2.3.1)^[1]. The cross-file citation is also fully supported for figrues Fig. F1^[1:1] and callouts Table. basic-grammar^[1:2] from the article A^[1:3].

1.4 Interactive Features

The interactive features are really useful for you to quickly check and manage your equations, listed in following table :

• For Preview, you can set the size of panel by Settings > categorical > styles > preview widget size.
• For Open in Split and Jump in a preview widget, if more than one editor is already open, it will reuse the existing adjacent editor instead of opening a new one. But in equations Panel, it will always open a new editor to prevent reusing existing editor.
• For Rename Tag, Select \tag{} to rename equation tag, select entire image ![[image.png|fig:1.1]] to rename figure tag.
• For Right-click Copy, You can customize what to copy in settings > Display (Categorical) > Equation Panel > Equation widget right click copy content, choose whether to copy the equation content with tag/braces.

2. Citations for Figures and Callouts

1) Figure Citations

1. Grammar

We use the enhanced image syntax to make figures citable :

%% We support both wiki link and markdown link format : 
%%wiki link format%%
![[James_Lovell.jpg|fig:3.1|desc:description]]

%%markdown link format%%
![fig:1.3|title:test|desc:Optional description](images.png) 

We have full markdown grammar support In title and description, so you can write inline equations in them. Use $\ref{fig:1.1}$ Fig. 1.1 to cite the following figure.

![[img/A minecraft image.png|fig:1.1|title: a minecraft picture|desc:This is a description for $\text{Minecraft}$ picture|214]]

We note that the plugin only render the title and description when fig:xx is added. If this conflicts with other plugins, you can toggle it by Settings > Categorical > Style > Render image captions and descriptions.

The title/description in the preview widget can be toggled in Settings > Categorical > Style > render figure info in preview widget

2. Support for Excalidraw and Section Preview

After v1.3.3, we can also cite the excalidraw image with same syntax Fig. 1.2.

To correctly render excalidraw, The excalidraw and excalidraw.md should be included in the settings > Display (Categorical) > Others > Extension names using Markdown renderer, the extension excalidraw.md must be added.

Section Citation : Since the grammar of external file link view ![[#1.4 Interactive Features|fig:1.6]] is same as image. When md is in the Extension names using Markdown renderer setting, we can even cite the section preview as Fig. 1.3.

Click here to jump to #1.4 Interactive Features

3. Limitations

This plugin doesn’t support creating caption for markdown link format images from web-link. But you can still cite it with Fig. 1.4.

Why we not support : We add caption inside class .internal-embed image-embed, and web-link image is rendered as <img> without this wrapper class. Creating element outside those images would cause some issue in editing. You can simply make it a local image file to solve this.

2) Callout Citations

1. grammar

The plugin support citing callouts with customized types, this give us flexibility to cite tables, theorems and any customized pieces.

You can configure customized prefix in Callout/Quote Citation Prefixes settings. By default only table: are enabled.

We give an example for how to cite a table :

Sales Data Q4 2024

Product	Revenue	Growth
Widget A	$100K	+15%
Widget B	$150K	+22%

Cite the table using: $\ref{table:2.1}$, rendered as Table. 2.1

Citation inside callouts must match case exactly. Example :

• Callout tag: > [!NOTE:1]
• Cite with: $\ref:{NOTE:1}$ (case-sensitive)

All figure and callout citations support syntax and interactive features in #1. Basic Equation Citations.

2. Custom Callout Colors

We also support customize callout colors by adding callout.css to Settings > Apperance > CSS Snippets, so you can write a beautiful callout like this (this take effect after adding this snippet):

Sales Data Q4 2024

This is a red callout table

Product	Revenue	Growth
Widget A	00K	+15%
Widget B	150K	+22%
Widget C	200K	+33%

3. Limitations

1. Currently the plugin don’t support auto-number and rename for callouts. Check en/5. Become a Pro for how to use callout citation better.

2. Unfortunately, we don’t support customize icon for callout yet. Since it use icon as data-callout. And we also use first field as citation label.

3. Use Auto-numbering System

You can automatically number all equations/figures in current file based on heading level by :

• Use the command Auto-number current file equations/figures
• Use the toolbar button

1) Auto-Number method and depth

You can customize the auto-number method and auto-number depth in settings > categorial > Auto-Number.

Auto Numbering Methods:

• Relative: Numbers based on relative heading hierarchy (2.1.1, 2.1.2, etc.)
• Absolute: Auto-number using the absolute heading level (1.1, 1.2 for #, etc.)

Numbering depth (1-6) : controls the max level to auto-number (1.1), (1.1.1)

Auto-number-prefix : this can be used if you are drafting on a book for a specific chapter. You can set it as 5., and in the section 1, the equation will have like \tag{5.1.4}.

2) Citation Updates During Auto-numbering

When auto-numbering runs, all citations are automatically updated to match new numbers. This allows you insert or delete equations any where and no need to worry about renumbering or broken citations.

There are 2 settings to resolve the conflict in auto-numbering process:

1. Auto delete conflict tag citations (default: true) : when a tag is renamed into another one, while the old citations for this tag still exist(not modified after auto-numbering), they will be automatically deleted to avoid wrong citations.
2. Auto delete unused tag citations (default: false) : if a citations is not used, it will be automatically deleted. (Only use this settings if you rely solely on auto-number for tag management).

3) Exclude equations for specific tag

The equations in callouts will not be included in auto-number system by default. So to prevent an equation from being auto-numbered, you should put it into a callout (see #166).

This equation will be excluded from Auto-number system : $$\iiint \nabla \cdot A dx = \iint A \cdot \vec{n} dS$$

You can still include equations in callouts by settings > categorical > Auto Number > Auto number equations in callouts

4) Only Number Important Equations

If a file contains many derivation steps but you only want to assign numbers to a few key equations you intend to cite :

1. Enable the option:
   • Settings > Categorial > Auto number tagged equations only
2. Add tags manually to the equations you care about:
   • At the end: use your shortcut (e.g. “Insert tag on cursor position auto-number”).
   • Mid-expression: insert with \tag{A} or some other, then run auto-numbering.

For my workflow, I suggest using \boxed for important equations.