Habit rules · Learning Editor

Habit rules mark the words you lean on: hedges, intensifiers, filler and the like. They run on your computer when you check a note, and keep that note up to date as you write. They're free, and nothing leaves your vault.

Each rule is a small file in your rules folder (Learning Editor/rules unless you changed it in settings). A rule carries its own examples. When the rules load, each one runs its examples. If one fails, that rule is switched off and you get a notice saying which. Open the panel; the Rules and profile section lists the switched-off rules and why.

Where rules come from#

Your rule files. Anything in the rules folder, subfolders included.
Your profile. Each habit under "Habits to coach" becomes a rule, with its quoted phrases. "Automatic check" lines become a rule too.
The starter pack. Common English habits that come with the plugin: hedges, intensifiers, softeners, throat-clearing openers, wordy frames, vague words and vague openers.

If two rules share an id, the first one in that list wins. So a file named hedges.md replaces the starter pack's hedges rule.

To get copies of the starter rules to edit, select Copy the starter habit rules in the Rules and profile section of the panel. It never overwrites a file that's already there.

What your profile protects#

Some things are never flagged, by any rule:

words and phrases under "Keep as written", and names from "House conventions"
short items under "Voice to keep" and "Never fix" (a word or a short phrase, like tho)
the quoted text of your rejected suggestions

A rule hit that touches any of these is left out.

A rule file#

A rule is a Markdown note with the rule in its frontmatter:

---
id: actually
category: cuts
kind: cut
phrases:
  - actually
  - as a matter of fact
message: Usually filler. The sentence stands without it.
flags:
  - It actually worked.
  - As a matter of fact, we left.
allows:
  - The actual cost was higher.
---
Anything below the frontmatter is for you. If there's no `message`, the first paragraph here is used instead.

You can also write the same fields as a whole .yml or .yaml file.

The fields#

Field	What it does
`id`	A short name, unique among your rules. Defaults to the file name.
`category`	Which group it shows in: `cuts`, `line`, `clarity`, `voice` or `mechanics`. Defaults to `cuts`.
`kind`	`cut` (the words can come out), `replace` (swap in `suggestion`) or `flag` (just a note). Defaults to `flag`.
`phrases`	Words or phrases to find. Matching ignores case, treats ' and ’ alike, and only matches whole words.
`regex`	A JavaScript regular expression, for what phrases can't say. Ignores case unless you add `case: sensitive`. `^` means the start of a line.
`message`	Why it's marked, in a few plain words. Shown on the card.
`suggestion`	What to write instead, for `replace` rules. A capital is added when the hit starts with one.
`flags`	Examples that must be marked. At least one is required.
`allows`	Examples that must not be marked.
`off`	`true` switches the rule off. Use it to turn off a starter rule or a profile habit by its id (profile habits have ids like `profile-hedges`).

A rule needs phrases or regex (or both), a message, and at least one flags example.

How a hit is shown#

A cut hit is offered as a cut: the phrase and the word next to it, with the phrase taken out ("really good" becomes "good"; at the start of a sentence the next word gets a capital). If there's no clean cut, it's shown as a note instead. A cut never adds words.
A replace hit offers the suggestion.
A flag hit is a note with the message.

Rules skip what isn't your prose: frontmatter, headings, block quotes, code, comments, link targets and embeds.

Other local checks#

Alongside your rules, the habits check also notes, in the Line group:

Close repeats: a word of five letters or more that comes back within about 40 words. The later uses are marked.
Leaned-on words: a content word you use six times or more in the note. The first use is marked, with the count.
Very long sentences: longer than 35 words, and much longer than your other sentences in the same note (more than two standard deviations above their average).
Sticky sentences: a sentence of 15 words or more where at least 60% are glue words, the small words like of, the, it and that that hold a sentence together without carrying its meaning. Only the three stickiest in a note are marked, and a sentence already marked as very long isn't marked again.

Habit rate#

The habit rate is how many rule hits there are per 100 words of your prose. The Progress section of the panel shows it for the note you're on, next to your average. It's a count, not a grade.

The rate can be written to the note's frontmatter as habit_rate, so you can follow it across posts. That's off unless you turn it on, because it changes the file: select Write habit rate to this note in the panel, or switch on Write habit rate to notes in Settings. See The panel.