# Markdownlint for Obsidian [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) catches style issues and common mistakes in markdown files. It works well with Obsidian, but several rules need disabling because they conflict with Obsidian conventions. ## Recommended `.markdownlint.jsonc` ```jsonc { // Line length — disabled for prose-heavy Obsidian notes "MD013": false, // First line heading — disabled because frontmatter comes first "MD041": false, // Inline HTML — Obsidian uses some HTML (e.g. <span>) "MD033": false, // Table column style — don't enforce spacing style "MD060": false, // Emphasis as heading — too many false positives with bold labels "MD036": false } ``` ## Why these rules are disabled | Rule | Name | Why | |------|------|-----| | MD013 | Line length | Obsidian notes are prose, not code — hard wrapping hurts readability | | MD041 | First line heading | YAML frontmatter comes before the first `#` heading | | MD033 | Inline HTML | Obsidian renders `<span>`, `<kbd>`, `<br>` etc. natively | | MD060 | Table column style | Strict column spacing is tedious for hand-edited tables | | MD036 | Emphasis as heading | Bold labels like `**Option 1:**` are common in notes and aren't headings | ## Pre-commit hook with Lefthook Run the linter automatically on staged files before each commit. Only lint the published folder (`Brain/`) to avoid noise from drafts and clippings. `lefthook.yml`: ```yaml pre-commit: commands: markdownlint: glob: "Brain/**/*.md" run: markdownlint-cli2 {staged_files} ``` The hook runs without `--fix` — it reports errors and blocks the commit, but never auto-deletes content (important for rules like MD053 that would silently remove footnote definitions). ## Install ```bash npm install -g markdownlint-cli2 # linter brew install lefthook # git hooks manager lefthook install # wire up the hooks ```