This document describes everything Fluidity does, precisely enough to predict it, along with the settings that govern each behavior. The architecture doc covers how it is done; this one is only about what happens.
Fluidity is under active development. Behavior described here without a caveat is what the plugin is built to do; anything not yet implemented says so. The roadmap tracks the difference.
Fluidity acts at the moment you pick a suggestion from the link completer, and only then. That single sentence answers most questions about scope:
- It does not change links already written in your notes. Fixing those is a different problem, with a different failure mode, and it is not what this plugin is for.
- It does not change how a link renders. What Fluidity produces is stored in the note, and reads the same in any other Markdown editor.
- It does not run on typing, on paste, or on save.
- It never rewrites text after Obsidian has inserted it. The link Obsidian writes is already the right one, so undoing it costs exactly what undoing any completion costs.
Add the property to the note's frontmatter:
---
fluent: true
---The value must be a real boolean. fluent: "true" is a string and does not mark the note
fluent, which is deliberate — Obsidian's property editor writes real booleans for a checkbox
property, and silently accepting a string would mean a typo changing how your links are written.
fluent: false, and a note with no such property at all, are treated identically: Fluidity does
nothing whatsoever to them.
The property name is configurable; see Settings.
When you pick a suggestion for a fluent note, and the link is not at a sentence start, Fluidity lowercases the display text:
… which is really about the [[Interiority|interiority]] of the practice.
At a sentence start, the capital stays exactly as it is, and Fluidity inserts precisely what Obsidian would have:
[[Interiority]] is the nature of the thing.
The rule is applied to the whole display text, every capital in it:
… an introduction to [[Object Oriented Programming|object oriented programming]] for beginners.
Lowercasing is locale-aware, so non-ASCII scripts behave as the reader's locale expects rather than as ASCII would have it.
The same rule applies to an alias of a fluent note, not only to its title. fluent says the
note names a common noun, and its aliases are alternative ways of saying that same common noun:
---
fluent: true
aliases:
- Interior Life
---… a question about the [[Interiority|interior life]] of the practice.
Aliases are read the way Obsidian itself reads them: only the aliases key (plural,
case-insensitive) is recognised, values are trimmed, empty ones are dropped, and both a single value
and a list are accepted. This matters because a disagreement here would be a disagreement with the
popup you are looking at.
If lowercasing the display text produces exactly what would have been inserted anyway — because the
title is already lowercase, or begins with a digit or a symbol — the suggestion is passed through
untouched. You will never see [[interiority|interiority]].
The transform runs when you select a suggestion, not while the list is being built. The completer popup therefore keeps showing your notes with their real, properly capitalised titles, which is what makes them readable in a list.
Embeds are left alone. ![[Interiority]] renders the note rather than reading as prose, and
what follows the pipe in one is a display argument rather than text. An embed is inserted exactly as
Obsidian would insert it, whether or not the note is fluent.
Typing # for a heading, ^ for a block reference, or | for an alias inside a link behaves
exactly as it does without the plugin. So does Shift+Enter, and so does every suggestion type
Fluidity does not explicitly handle. In particular, block-reference completions are never
intercepted — selecting one writes a block id into the target note, and that is not something a
plugin should be adjusting on its way past.
This is the part worth reading carefully, because it is where "it did the wrong thing" usually comes from.
Fluidity looks at the text on the line before the [[ you are completing, and asks whether a
sentence begins at that point. Before testing anything, it ignores:
- Trailing emphasis markers —
*,**,***,_,__,___,==,~~. Emphasis opened immediately before a link does not move the sentence. - Opening quotes and brackets —
",', the curly quotes,(,[, and their kin.
So **[[Interiority]]** is … and ("[[Interiority]] … both count as sentence starts.
What remains counts as a sentence start when it is:
| The preceding text is… | Example |
|---|---|
| empty — the link starts the line | [[Interiority]] is … |
| a heading marker | ## [[Interiority]] |
| a blockquote marker | > [[Interiority]] is … |
| a callout header | > [!note] [[Interiority]] is … |
a list bullet — -, *, or + |
- [[Interiority]] is … |
| an ordered-list marker | 1. [[Interiority]] is … |
| a checkbox | - [ ] [[Interiority]] is … |
terminated by ., !, ?, :, or ; |
Note: [[Interiority]] is … |
terminated by 。, ！, or ？ |
終わり。[[Interiority]] … |
The terminator cases need whitespace after the punctuation, except for the CJK terminators, which do not take a following space in ordinary use.
: and ; are included because a colon is how most people write a lead-in, and what follows one
reads as the start of a new clause. This is a judgement call rather than a grammatical rule, and it
is the one most likely to be made configurable later.
A . is not a sentence boundary when it is:
- inside a decimal number —
3.14 is the [[Interiority]] …is mid-sentence, - part of a common abbreviation —
e.g.,i.e.,etc.,Dr.,Mr.,vs.and friends, - inside a URL,
- inside inline code.
A link at the very start of a line is treated as a sentence start without looking at the line above it. In Obsidian a paragraph is normally a single line, so this is correct nearly always, and when it is wrong the result is a capital that should have been lowered — the conservative failure, and one you can see and fix.
The casing rule lowercases the entire display text. This is right for the titles it was built for:
[[Object Oriented Programming|object oriented programming]] ✓
[[Interiority|interiority]] ✓
And it is wrong when a title contains a genuine proper noun:
[[History of France|history of france]] ✗ should be "history of France"
This is known and accepted for the first version of the plugin, not an oversight. The purpose of v1 is to establish that patching the completer is reliable enough to build on, and a casing rule with no configuration surface keeps that question clean. Every casing decision goes through one small pure function, so replacing the rule later changes nothing else.
The plan is not a dictionary of proper nouns — that would be a large amount of machinery to be subtly wrong in a new way. It is a per-note override, expressed in a small language, designed together with the alias conventions the second feature needs. The roadmap has the reasoning.
Until then, the workaround is to not mark such a note fluent, and to write its links as you always
have.
Not implemented yet. The intent is that picking an alias which names a sub-topic of a note inserts a link to the heading that sub-topic lives under, rather than to the top of the note:
Before see [[Big Note|the thing about tides]]
After see [[Big Note#Tides|the thing about tides]]
Two things about this are already settled. Obsidian's own composer supports it directly — a suggestion whose path carries a subpath produces the sectioned link without any string-building on our side — and the data needed to find the heading is already in the metadata cache, so no file has to be read. What it waits on is a written convention for how alias lists are structured, which is what makes "the heading this alias belongs to" a definite thing rather than a guess.
See the roadmap.
Settings → Fluidity.
| Setting | Default | What it does |
|---|---|---|
| Fluent titles | on | The master toggle. Off, nothing about a completion is changed. |
| Fluent property | fluent |
Which frontmatter property marks a note fluent. |
Turning fluent titles off does not leave a patched completer sitting idle but instead removes the patch outright, so that off means Obsidian is running the code it would run without Fluidity installed.
Renaming the property takes effect on the next completion and does not migrate anything; notes
still carrying the old property simply stop being treated as fluent. It exists for vaults where
fluent already means something else. Leaving the field empty means fluent, which is what the
greyed-out placeholder is telling you; surrounding spaces are dropped, because a trailing one is
invisible in both this field and the property editor and would read as the plugin being broken.