Obsidian Linter

Obsidian Linter is an Obsidian.md plugin designed to enforce uniform patterns across your notes. It allows users to specify specific rules and settings to standardize note structure.

Supported rule categories include:

• YAML frontmatter: Formatting and structure of metadata.
• Markdown headings: Consistency in heading levels and styles.
• Github flavored footnotes: Standardizing footnote syntax.
• General markdown content: Rules affecting the body of the note.
• Spacing: Managing whitespace and indentation.
• Pasting content: Controlling how content is formatted when pasted into the app.

The Obsidian Linter uses remark-math as its math block parser. Note that this parser differs from Obsidian's internal parser, which may lead to discrepancies in how math blocks or inline math are identified.

Expected Formats

• Inline Math: Use the format $MATH_HERE$. The number of dollar signs used for inline math should be less than the number used for math blocks.
• Math Blocks: Use the following structure:

$$
MATH_HERE
$$

The Linter includes logic to attempt to convert inline math blocks into math blocks when they contain the minimum required number of $ signs at the start.

Each rule in the Obsidian Linter is a self-contained set of logic designed to run independently.

Important Note on Rule Conflicts: Because rules are independent, enabling certain rules together can cause unexpected or undesired results if their logic overlaps. For example, enabling both "Paragraph blank lines" and "Two Spaces Between Lines with Content" may result in conflicts because they target similar structural elements in different ways. Always check for rule overlaps when configuring your settings.

Before configuring paste rules, be aware of the following constraints:

• Shortcut Support: The plugin only works with the standard cmd/ctrl + v shortcut. It does not work with the p operator in Vim (though cmd/ctrl + v in normal or insert mode works).
• URL Detection: To prevent conflicts with plugins like Auto Link Title or Paste URL into Selection, paste rules will not trigger if a URL is detected in the clipboard.
• Mobile Usage: On mobile, you must use the Tap and Hold -> Paste action to ensure paste rules are applied.
• Multi-cursor Behavior: When performing a multi-cursor multiline paste, cursors will remain at their original positions rather than moving to the end of the newly pasted values.

The date modified value in your YAML frontmatter is not derived from the file's actual system metadata (the OS-level 'last modified' timestamp). Instead, the Linter sets this value to the exact moment the Linter rule triggers an update to the file.

Why this matters: If a file is rarely updated, the system metadata might be very old. The Linter's date modified rule will update the YAML to the current time when the rule runs, ensuring the frontmatter reflects when the Linter last processed/modified the file. This value should typically be within 5 seconds of the actual file metadata timestamp when the Linter is active.

By default, the rule uses linter-yaml-title-alias to track the last known title. If Use the YAML key specified by Alias helper key to help with filename and heading changes is true, the linter will replace the old alias with the new one when the filename or H1 changes, rather than adding a duplicate.

You can customize the tracking key by setting Alias helper key to a different name (e.g., title).

# Example: Replacing old filename with new filename

# Before:
---
aliases:
  - Old Filename
  - Alias 2
linter-yaml-title-alias: Old Filename
---

# After:
---
aliases:
  - Filename
  - Alias 2
linter-yaml-title-alias: Filename
---

The Obsidian Linter plugin formats and styles notes using a collection of independent rules.

Key Concepts

• Configurability: Rules can be toggled and configured individually within the plugin settings.
• Independence: Each rule is designed to run as its own set of logic.
• Rule Conflicts: Because rules are independent, enabling certain rules together can cause unexpected results if they target the same content.

Example of a conflict: Using Paragraph blank lines alongside Two Spaces Between Lines with Content may result in undesired behavior because both rules overlap in the content they target.

When using YAML rules in the Obsidian Linter, be aware of the following technical limitations:

• Regex-based parsing: The linter currently uses regular expressions to parse YAML key values rather than a dedicated YAML library. This means certain complex YAML formats may not be parsed correctly.
• Comment interference: Including comments within the value of a YAML key may cause issues with rule execution, such as failing to sort keys correctly or failing to retrieve the key's value.
• Blank line removal: If you use the linter to sort keys or modify the order of keys in your YAML frontmatter, existing blank lines may be removed.
• General accuracy: While the rules cover most common Obsidian YAML use cases, they are not perfect and may not support all valid YAML syntax.

The paragraph-blank-lines rule adds a blank line if a paragraph has a subsequent line that does not end with any of the following line-break indicators:

• 2 or more spaces
• <br>
• <br/>
• \ (backslash)