Skip to content

About

Check your Obsidian plugin against the official developer guidelines.

Topics

Resources

Contributing

Stars

114 stars

Watchers

4 watching

Forks

Repository files navigation

eslint-plugin-obsidianmd

Upgrading from 0.5.x? See Upgrading to 0.6.0, and from 0.5.0 also Upgrading to 0.5.1. From 0.4? Start with Upgrading to 0.5.0. All are summed up in the changelog.

Installation

You'll first need to install ESLint:

npm i eslint --save-dev

Next, install eslint-plugin-obsidianmd:

npm install eslint-plugin-obsidianmd --save-dev

The plugin needs Node.js 20.19+, 22.13+ or 24+, ESLint 9.19 or later, typescript-eslint 8.35.1 or later, and a TypeScript version your typescript-eslint supports (4.8.4 or later; typescript-eslint 8 supports up to 6.0). npm installs typescript and typescript-eslint alongside the plugin if your project does not already have them. TypeScript 7, the native compiler, has no JavaScript API yet, so typescript-eslint and this plugin cannot use it; npm refuses typescript@7 next to typescript-eslint 8 with an ERESOLVE error. Keep TypeScript 5 or 6 in your devDependencies. typescript-eslint 8.70.1 or later is recommended: it fixes a no-unnecessary-type-assertion false positive on an empty object asserted to a Record type alias (typescript-eslint#12856). The configuration examples below import defineConfig and globalIgnores from eslint/config, which ESLint added in 9.22. On an older ESLint, write { ignores: [...] } instead of globalIgnores([...]), and export the array without defineConfig, or, where an example uses extends, wrap it in tseslint.config(...) instead.

On ESLint 10, npm prints ERESOLVE overriding peer dependency warnings when it installs the plugin, and npm ls --all and npm ls eslint exit with invalid: eslint@10…. Three packages the plugin bundles do not declare ESLint 10 support yet: @microsoft/eslint-plugin-sdl, eslint-plugin-import, and eslint-plugin-react, which @microsoft/eslint-plugin-sdl installs. Linting works, so you can ignore the warnings. With npm's strict-peer-deps setting on, the install fails instead; turn the setting off or use ESLint 9.

The plugin reads Obsidian's own type definitions rather than bundling a copy, so your project needs obsidian installed as well. Plugin projects generated from the sample plugin already have it:

npm install obsidian --save-dev

Without it, no-unsupported-api silently reports nothing. See that rule's docs for which obsidian versions give useful results.

Usage

Add the recommended configuration to your eslint.config.mjs. This enables all recommended rules, including ESLint core, typescript-eslint type-checked rules, and Obsidian-specific rules.

// eslint.config.mjs
import { defineConfig, globalIgnores } from "eslint/config";
import obsidianmd from "eslint-plugin-obsidianmd";

export default defineConfig([
  // Build output and the sample plugin's Node build scripts are not plugin code.
  globalIgnores(["node_modules", "dist", "main.js", "esbuild.config.mjs", "version-bump.mjs"]),
  ...obsidianmd.configs.recommended,
  {
    languageOptions: {
      parserOptions: {
        projectService: {
          allowDefaultProject: ["eslint.config.*"],
        },
      },
    },
    rules: {
      // example: turn off a rule from the recommended set
      "obsidianmd/sample-names": "off",
      // Set @typescript-eslint/* rules to "warn" or "error" in a block with
      // `files: ["**/*.ts"]`; see "Overriding rules" in docs/configuration.md.
    },
  },
]);

The globalIgnores entry follows the official sample plugin's layout: main.js is the bundled build, and esbuild.config.mjs and version-bump.mjs are Node scripts. None of them is plugin source or in your tsconfig.json, so without it ESLint fails on them with "was not found by the project service". List your own build output and scripts there.

If your plugin has no build step and you write main.js yourself, it is your source: leave it out of globalIgnores, add it to allowDefaultProject, and declare the CommonJS globals Obsidian loads it with. Ignoring files shows the full setup. For a plugin written in JavaScript with its sources in src/ or elsewhere, see Plugins written in JavaScript: with the parserOptions block above and no jsconfig.json, every file fails with "was not found by the project service".

The parserOptions block is required because the recommended config includes type-checked rules that need access to your TypeScript project. allowDefaultProject ensures files not listed in your tsconfig.json (like the ESLint config file itself) are still linted without errors. See the configuration guide for details on why this is needed and how to customize it.

Note: You do not need to separately add eslint.configs.recommended or tseslint.configs.recommended — both are already included in the recommended config.

The recommended config also lints files that are not source, matching package.json, manifest.json and LICENSE by name. Run ESLint from the project root: a lint script scoped to your sources — eslint src — never visits them, and their checks silently do nothing. See Files linted beyond your source.

For advanced usage, see the configuration guide:

To give another plugin's rule a message of your own, wrap it with obsidianmd.withCustomMessages().

Configurations

Name
✅ recommended
🇬🇧 recommendedWithLocalesEn

Rules

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
🚫 Configurations disabled in.
✅ Set in the recommended configuration.
🇬🇧 Set in the recommendedWithLocalesEn configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.
💭 Requires type information.

Name                                          Description 💼 ⚠️ 🚫 🔧 💡 💭
commands/check-callback-uses-checking Require checkCallback and editorCheckCallback to use their checking parameter. ✅ 🇬🇧
commands/no-command-in-command-id Disallow using the word 'command' in a command ID. ✅ 🇬🇧 💡
commands/no-command-in-command-name Disallow using the word 'command' in a command name. ✅ 🇬🇧 💡
commands/no-default-hotkeys Discourage providing default hotkeys for commands. ✅ 🇬🇧 💡
commands/no-plugin-id-in-command-id Disallow including the plugin ID in a command ID. ✅ 🇬🇧 💡
commands/no-plugin-name-in-command-name Disallow including the plugin name in a command name. ✅ 🇬🇧 💡
detach-leaves Don't detach leaves in onunload. ✅ 🇬🇧 🔧
editor-drop-paste Require checking evt.defaultPrevented and calling evt.preventDefault() in editor-drop/editor-paste handlers. ✅ 🇬🇧
hardcoded-config-path Disallow hardcoded .obsidian config paths. Use Vault#configDir instead. ✅ 🇬🇧
no-await-chainable Disallow awaiting Setting and UI components, whose then is for chaining and never settles a promise. ✅ 🇬🇧 💭
no-forbidden-elements Disallow attachment of forbidden elements to the DOM in Obsidian plugins. ✅ 🇬🇧
no-global-this Disallow global and globalThis. Use window or activeWindow for popout window compatibility. ✅ 🇬🇧 🔧 💡
no-misused-promises Disallow Promises in places not designed to handle them, without treating Obsidian's chaining then as a Promise ✅ 🇬🇧 💭
no-nodejs-modules Disallow importing Node.js built-in modules unless guarded by Platform.isDesktop ✅ 🇬🇧
no-plugin-as-component Disallow anti-patterns when passing a component to MarkdownRenderer.render to prevent memory leaks. ✅ 🇬🇧 💭
no-sample-code Disallow sample code snippets from the Obsidian plugin template. ✅ 🇬🇧 🔧
no-static-styles-assignment Disallow setting styles directly on DOM elements, favoring CSS classes instead. ✅ 🇬🇧
no-tfile-tfolder-cast Disallow type casting to TFile or TFolder, suggesting instanceof checks instead. ✅ 🇬🇧
no-unsupported-api Disallow usage of Obsidian APIs not available in the plugin's minimum app version ✅ 🇬🇧 💭
no-view-references-in-plugin Disallow storing references to custom views directly in the plugin, which can cause memory leaks. ✅ 🇬🇧 💭
object-assign Discourage using Object.assign with two arguments ✅ 🇬🇧 💡
platform Disallow use of navigator API for OS detection ✅ 🇬🇧
prefer-abstract-input-suggest Disallow Liam's frequently copied TextInputSuggest implementation in favor of the built-in AbstractInputSuggest. ✅ 🇬🇧
prefer-active-doc Prefer activeDocument over document for popout window compatibility. ✅ 🇬🇧 💡
prefer-create-el Prefer Obsidian DOM helpers (createEl, createDiv, createSpan, createSvg, createFragment) over native DOM methods. ✅ 🇬🇧 🔧 💡 💭
prefer-file-manager-trash-file Prefer FileManager.trashFile() over Vault.trash() or Vault.delete() to respect user settings. ✅ 🇬🇧 💡 💭
prefer-get-language Prefer Obsidian's getLanguage() over localStorage.getItem('language') and i18next-browser-languagedetector for detecting the user's language. ✅ 🇬🇧 💡
prefer-instanceof Prefer .instanceOf(T) over instanceof T for cross-window safe type checks on DOM Nodes and UIEvents. ✅ 🇬🇧 🔧 💡 💭
prefer-window-timers Prefer window.setTimeout() and related timer functions over bare global calls for popout window compatibility. ✅ 🇬🇧 🔧 💡
regex-lookbehind Using lookbehinds in Regex is not supported in some iOS versions ✅ 🇬🇧
rule-custom-message Allows redefining error messages from other ESLint rules that don't provide this functionality natively. ✅ 🇬🇧 🔧 💡
sample-names Rename sample plugin class names ✅ 🇬🇧
settings-tab/no-deprecated-display Disallow a leftover display() method on PluginSettingTab subclasses once getSettingDefinitions() is implemented and minAppVersion is 1.13.0 or later. ✅ 🇬🇧 💡
settings-tab/no-manual-html-headings Disallow using HTML heading elements for settings headings. ✅ 🇬🇧 🔧 💡
settings-tab/no-problematic-settings-headings Discourage anti-patterns in settings headings. ✅ 🇬🇧 🔧 💡
settings-tab/prefer-setting-definitions Encourage PluginSettingTab subclasses to implement getSettingDefinitions() so settings appear in Obsidian 1.13+ settings search. ✅ 🇬🇧
settings-tab/prefer-update-over-display Prefer this.update() over this.display() to refresh a PluginSettingTab on Obsidian 1.13+. ✅ 🇬🇧 🔧 💡
settings-tab/require-display Require a display() method on PluginSettingTab subclasses when minAppVersion is below 1.13.0. ✅ 🇬🇧
ui/sentence-case Enforce sentence case for UI strings ✅ 🇬🇧 🔧
ui/sentence-case-json Enforce sentence case for English JSON locale strings 🇬🇧 🔧
ui/sentence-case-locale-module Enforce sentence case for English TS/JS locale module strings 🇬🇧 🔧
validate-license Validate the structure of copyright notices in LICENSE files for Obsidian plugins. ✅ 🇬🇧
validate-manifest Validate the structure of manifest.json for Obsidian plugins. ✅ 🇬🇧
vault/iterate Avoid iterating all files to find a file by its path ✅ 🇬🇧 💡

UI sentence case

Checks UI strings for sentence case. The rule reports warnings but doesn't change text unless you run ESLint with --fix and enable allowAutoFix.

  • Off in the recommended configs from 0.5.0 (0.3.0 meant to turn it off, but it stayed on through 0.4.2); turn it on yourself, as in the example below
  • Locale checks for English JSON and TS/JS modules are on in recommendedWithLocalesEn
  • By default allows CamelCase words like AutoReveal
  • Set enforceCamelCaseLower: true to flag CamelCase as incorrect
  • brands and acronyms replace the built-in lists (which include Obsidian, GitHub, URL and PDF) rather than adding to them, so list every brand and acronym your UI text uses

Usage (flat config)

// eslint.config.mjs
import { defineConfig, globalIgnores } from "eslint/config";
import obsidianmd from "eslint-plugin-obsidianmd";

export default defineConfig([
  // Build output and the sample plugin's Node build scripts are not plugin code.
  globalIgnores(["node_modules", "dist", "main.js", "esbuild.config.mjs", "version-bump.mjs"]),
  ...obsidianmd.configs.recommended,
  // Or include English locale files (JSON and TS/JS modules)
  // ...obsidianmd.configs.recommendedWithLocalesEn,

  {
    languageOptions: {
      parserOptions: {
        projectService: {
          allowDefaultProject: ["eslint.config.*"],
        },
      },
    },

    // Optional project overrides
    rules: {
      "obsidianmd/ui/sentence-case": [
        "warn",
        {
          // These replace the built-in lists: add back any you use, such as "Obsidian" or "URL"
          brands: ["YourBrand"],
          acronyms: ["OK"],
          enforceCamelCaseLower: true,
        },
      ],
    },
  },
]);

Notes

  • Hyphenated words: mid-sentence, Auto-Reveal becomes auto-reveal. At the start of a sentence the default loose mode keeps Auto-Reveal, and enforceCamelCaseLower (or mode: "strict") gives Auto-reveal
  • Locale file patterns in recommendedWithLocalesEn: JSON files and modules (.ts, .js, .cjs, .mjs) named en, en-*, en_* or en.* (en.json, en-US.ts, en.messages.json), with en in any case, or under a directory named so (en/, en-US/); not english.json or entries.json

Known limitations

Sentence detection splits at the dot of an abbreviation it does not know, such as "Dr." or "Inc.", and expects the next word to start with a capital: "See Acme Inc. products" is reported. After "e.g.", "i.e.", "etc." and similar abbreviations the next word may take either case. Use single sentences or adjust rule options when needed.

About

Check your Obsidian plugin against the official developer guidelines.

Topics

Resources

Contributing

Stars

114 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages