A couple of weeks ago I talked about how to organize your properties in Obsidian using Obsidian Linter.

That is one of my favorite uses for Obsidian Linter, but there is much more that this plugin can do. If you value consistency in your notes, but don’t want to have to manually keep everything consistent, then perhaps Linter is for you.

Interested? Let’s dive in.

Table of Contents

• What is a “Linter”?
• Quick Warning
• Installing Linter
• How Does a Linter Work?
• Excluding Folders
• Basic Setup for Obsidian Linter
• Property Settings
• Header Settings
• Footnote Settings
• Content Settings
• Spacing Settings
• Paste Settings
• Custom Settings
• Debug Settings
• Conclusion

What is a “Linter”?

It’s kind of a strange word, isn’t it? Linting comes from the computer world, and it essentially means “checking that a file meets a standard specification”. A Linter is a tool that checks if a certain file meets your standards, and if not, fixes it.

Like one of those sticky rollers that removes lint from your clothes: a linter removes unwanted inconsistencies from your notes.

Linters are great for keeping files consistent. In my previous article I talked about using Linter to specify an order for Obsidian Properties. This is a perfect use for a Linter, because 1) it’s helpful for those properties to always be in the same order, and 2) it would be repetitive and labor intensive work to do by hand.

As a general rule, if you’re manually changing the formatting of your files across hundreds (or thousands) of files, then you should perhaps be using a Linter. It allows you to automate what would otherwise be a labor intensive process.

In case that description leaves you scratching your head, here are a few examples of things that a Linter can do for you. These are changes that Linter can make automatically, to as many files as you want, without you having to lift a finger:

• Organize your metadata
• Capitalize all headings
• Add heading to all files (based on the file title)
• Fix syntax errors in your metadata
• Fix formatting issues with copy/pasted text
• And so much more…

Quick Warning: Linter Can Break Your Files

This may go without saying, but I’m going to say it anyway: BE CAREFUL whenever you’re changing settings in Linter, and make sure your files are backed up. Linter has the ability to change every file in your vault, and if you don’t configure it properly, it could break every file in your vault. So proceed with caution.

By default Linter does nothing, so make sure you understand what you are changing before you change anything in the settings.

The goal of this article is to empower you to use this incredible tool, without losing any of your important work. And the best way to ensure that is to start by backing up your work.

Installing Linter

If you want to use Linter, you first need to install it. Here’s how:

1. Install Linter (click to open in Obsidian)
2. Enable Linter in your community plugins

Once you have installed and enabled Linter, we’re ready to move on to the setup!

How Does Linter Work?

Obsidian Linter has a few different steps that it runs through. First of all, you have to specifically initiate a lint for it to do anything. There are a few different ways you can initiate Linter, and we’ll get into those in a bit.

After you instruct Linter to lint one or more of your files, Linter checks to make sure the relevant file is not excluded. If not, then Linter attempts to run the rules that you have configured.

Excluding Folders

If you have old files that you don’t want linted, it’s a good idea to exclude those files from Linter. That will prevent Linter from ever modifying those files.

That will ensure—no matter which method you choose to lint your files—that those files won’t be changed. See “Folders to ignore” in the screenshot below: that is where you can exclude as many folders as you like.

Basic Setup for Obsidian Linter

By default, Linter doesn’t do anything. Even if you install and enable it, the plugin doesn’t do anything until you configure it.

The configuration screen in Linter can be a bit overwhelming at first. Here’s what it looks like the first time you install it:

The first thing we need to setup is a trigger. Linter only runs if we tell it to, so we need some way to tell it to run.

One way to do this is with the command palette. If you open the command palette, and type “Lint”, you will see several options for Linter:

This is helpful if you only want to lint a few files, but it’s not great if you want to keep all of your files consistent. If you want Linter to run automatically in the background, then you’re going to want to turn on “Lint on File Change”. Back to settings:

If you use this option, then Linter will run whenever you close a file. This is my favorite option, and it ensures that every new note you create will be linted.

If you want a little more control, instead of linting on change, you can lint on save:

The problem with this method is that you have to remember to do it. The default is to not lint your files, and they will only receive linting if you press ctrl+s.

I recommend enabling “Lint on File Change”, and instead of manually linting the files you do want to lint, you should exclude the files you don’t want linted. That way you can set up Linter once, and never think about it again.

Property Settings

Linter has nine different tabs that all control different parts of your notes. We’re going to go through each of those tabs now, and I’m going to highlight the features that I think are the most helpful. For a complete list of what Linter can do, check out the official documentation.

After the general settings, the next tab is YAML settings. If you’re new to Obsidian, YAML is now called Properties in Obsidian, but YAML and Properties refers to the same thing: the metadata for each of your notes.

Here are some of the metadata issues that Linter can fix for you:

• Escape special characters
  • Use this if you want to use characters such as :, ', ", or [] in your metadata
• Format Tags in YAML
  • Many people (myself included) have included the incorrect tag syntax in their properties (tags: #tag instead of tags: tag). This fixes that.
• Format YAML Array
  • Fixes common YAML syntax errors. This isn’t as necessary if you’re using Properties, because much of this is now built-in.
• Insert YAML attributes
  • If you want certain properties to exist in all of your notes, you can use this.
• Move Tags to YAML
  • If you include tags in the body of your notes, you can use this to convert them to Properties.
• Remove YAML keys
  • If you want to clean up old metadata that you no longer use, this is a handy tool to use
• YAML Key Sort
  • I’ve written about this one before. If you want your Properties to always have a consistent order, use this!
• YAML Timestamp
  • Adds date created/updated metadata to notes. I personally use another plugin for this, but it could be handy doing it here.
• YAML Title Alias
  • Handy if you want to use a header in your file that is different from the filename. If so, this will add the top level header to the file as an alias.
• YAML Title
  • Inserts the title of the file into your YAML, into a key of your choosing.

Automating your properties can be extremely useful. But you can also automate the contents of your note: that’s what we’ll talk about next.

Header Settings

The third tab in Linter has to do with headings. If you want help keeping your headers consistent, then this is the section for you!

• Capitalize Headings
  • Linter can automatically adjust the capitalization of your headings. I like to use Title Case here: I think it looks cleaner, but it’s up to you.
• File Name Heading
  • Inserts a header into your notes if one doesn’t exist. Personally I prefer to use the “Show Inline Title” option built-in to Obsidian.
• Header Increment
  • This insures that your headers are in a logical sequence. H2 follows H1, H4 follows H3, etc.
• Headings Start Line
  • Removes white space in front of headings
• Remove Trailing Punctuation in Heading
  • Removes your choice of punctuation from the end of your headers

Footnote Settings

I’m a big fan of footnotes. But they’re a little tricky to use in Markdown. I use a plugin to make creating footnotes easier, and Linter keeps them looking clean. Here are your footnote options in Linter:

• Footnote after Punctuation
  • Ensures footnote references go after punctuation (like this. [^1] Not this[^1].)
• Move Footnotes to the bottom
  • If you accidentally add content below your footnotes, or add a footnote mid-note, this will fix that. Handy combined with other automations that append to the bottom of your file.
• Re-Index Footnotes
  • Sometimes footnotes get out-of-order in Obsidian. Maybe you add one to the bottom of the file, and then another one half-way up. If you do that, the footnotes will be out-of-order. But Linter will happily fix that for you.

I personally use all three of these, and if you use footnotes, I recommend that you do the same. Along with the footnotes plugin, it makes footnotes in Obsidian painless.

Content Settings

• Auto-correct Common Misspellings
  • Obsidian comes with its own built-in spell checker. But to use it you have to right-click on each of your misspellings, and fix them yourself. If you turn this on, Linter will fix misspellings automatically. Handy.
• Blockquote Style
  • Basically adds or removes whitespace after the > character, so that your blockquotes look consistent
• Convert Bullet List Markers
  • This is handy if you copy/paste lists into your vault. If you have lists that use actual bullet points, this will convert them to the correct Markdown syntax
• Emphasis Style
  • This one is a cool one: in Markdown there are two ways to italicize content, either with underscores or asterisks. This setting will ensure you use one or the other. You can specify which one you prefer, or Linter will go with the first style it finds in each note.
• No Bare URLS
  • In Obsidian you can paste a URL, and Obsidian will automatically turn it into a link. But that isn’t true for all Markdown processors: technically URLs in Markdown should be surrounded by angle brackets (like <https://google.com>). This setting will do that for you. I don’t bother with it, but if you use multiple Markdown tools, this could be handy.
• Ordered List Style
  • Ensures consistent formatting for ordered lists. Super handy if you use ordered lists, Linter will make sure the numbers count up properly.
• Proper Ellipsis
  • Replaces three dots with an ellipsis, just like your phone does!
• Quote style
  • Handy if you like to use the proper “smart quotes” in your documents. I don’t use this though, instead I use the “smart typography” plugin, which is a little more configurable.
• Remove Consecutive List Markers
  • Handy for copy pasting. Converts - - list item to - list item.
• Remove Empty List Markers
• Remove Hyphenated Line Breaks
  • Useful when copy-pasting from textbooks
• Remove Multiple Spaces
  • Always a good thing, IMO. Ignores indentation.
• Strong Style
  • Similar to Emphasis Style above, ensures that your bold text uses a consistent syntax.
• Two Spaces Between Lines with Content
  • Adds spaces to the end of single lines of text. That way when they render, they show up with the proper spacing.
• Unordered List Style
  • Ensures unordered lists use a consistent style

That was a lot of stuff! If you write a lot in Obsidian, I suggest you give some of these a try. They can save you a lot of time.

Spacing Settings

White-space can be a pain to manage. Linter makes it much easier.

• Compact YAML
  • Removes white-space around your YAML config. Probably not needed if you use Properties, Obsidian maintained this for you now.
• Consecutive Blank Lines
  • If your note has more than two new-lines in a row, this setting will clean that up.
• Convert Spaces to Tabs
  • Converts leading space characters into tabs. Also allows you to configure tab size
• Empty Line around Blockquotes
  • Ensures that there are empty lines surrounding a blockquote. The next three options are similar:
• Empty Line around Code Fences
• Empty Line around Math Blocks
• Empty Line around Tables
• Heading blank lines
  • Allows you to configure the spacing around your headings.
• Line Break at Document End
  • Ensures that there is exactly one line break at the end of every note
• Move Math Block Indicators to Their Own Line
• Paragraph Blank Lines
  • Ensures every paragraph has exactly one blank line before and after
• Remove Empty Lines Between List Markers and Checklists
• Remove Link Spacing
  • Removes spacing around link text
• Remove Space around Characters
  • Allows you to remove space around certain characters, such as en and em dashes
• Remove Space Before or After Characters
  • Allows you to configure characters that should never have spaces before or after them. By default this removes spaces before these characters: ,!?;:).’”] And it removes spaces after these characters: ¿¡‘“([.
• Space after list markers
  • Ensures a single space exists after list markers and checkboxes
• Space between Chinese Japanese or Korean and English or numbers
• Trailing spaces
  • Removes extra spaces after every line

Paste Settings

If you copy/paste into Obsidian a lot, then Linter may become your new best friend. Use these settings to fix broken formatting when you paste things into your vault.

• Add Blockquote Indentation on Paste
  • If you paste text inside a quote, this will fix the formatting
• Prevent Double Checklist Indicator on Paste
  • If you paste a checkmark into an item that already has a checkmark, this will remove the duplicate
• Prevent Double List Item Indicator on Paste
  • If you paste a list into a list, this will remove the duplicate list indicator
• Proper Ellipsis on Paste
  • Replaces three consecutive dots with an ellipsis on paste
• Remove Hyphens on Paste
  • Similar to Remove Hyphenated Line Breaks, except this one fixes on paste
• Remove Leading or Trailing Whitespace on Paste
  • Removes any leading non-tab whitespace and all trailing whitespace on paste
• Remove Leftover Footnotes from Quote on Paste
  • Removes footnotes from an external source, since they probably won’t work in your vault anyway
• Remove Multiple Blank Lines on Paste
  • Cleans up excess blank lines in pasted content

Custom Commands

Linter also allows you to create your own custom commands. These can be complex, finicky, and dangerous, so they are outside the scope of this article. But if you want more info on creating your own Linter Custom Commands, let me know, and maybe we’ll do a deep dive in the future.

Debug Settings

Linter is a complex plugin, and as a result, things can occasionally go wrong. If you have problems with Linter, it can help to turn on the debug settings and look at what the program is telling you.

I haven’t needed this unless I’m developing custom commands, so for basic use I don’t think you’ll need it either. But it’s there if you need it.

Conclusion

Linter is an incredibly useful tool, and can save you a lot of time. If you’re interested in automating some of the work you do in Obsidian, then Linter is a great place to start.

Is Linter useful for you? I’d love to hear how you use it, let me know in the comments below!