How to Force Spotlight to Index Markdown Files in El Capitan

This was the key
This was the key

Sometime this past summer, I noticed Spotlight was no longer indexing my Markdown documents. This was problematic because I rely on Spotlight search to locate documents containing markup I want to change. For instance, I recently wanted to decrease my reliance on the generic <div> container, and instead use more semantic tags such as <section> and <aside>. I would have liked to have been able to search Spotlight for all my posts containing the string of text <div class="update">, so I could change that to <aside class="update">.

But searching for such a string of text like <div class="update"> led to zero results. I was forced to simply open every single one of my files and search for the string and replace as necessary. Needless to say, this was both incredibly frustrating and an incredible waste of time.

There were some clues. was constantly throwing Spotlight errors such as XPC connection was invalidated, so I assumed it was some Spotlight error I introduced via brew or some other command line hackery. I scoured the web for answers. Almost everything pointed to El Capitan’s rootless issues.

Several clean restores and countless Spotlight re-indexes later, the issue still wasn’t fixed.

It was maddening.

I hate you Spotlight.
I hate you Spotlight.

Then this morning I had a breakthrough.

What if it’s not entirely a Spotlight issue? What if it’s a Markdown issue?

I did some more searching and landed on Hilton Lipschitz’s A Yosemite Markdown Spotlight Importer.

Turns Out™ this isn’t an El Capitan-only problem. It’s been around for years: OS X has trouble indexing Markdown files with the extension .md. I tested this by renaming my file to about.txt. I waited a few seconds, and then Spotlight easily found a string of text contained in the file. I then changed it back to .md and Spotlight failed to find given the same search query as before.

Now, I’m not sure why this is something that only started happening a few months ago. Spotlight had no problems finding text strings within Markdown documents before this period of Spotlight failures.

What’s important is that the suggestion found on Lipschitz’s page worked for me (with a little tweaking).

Here’s how I fixed it:

  1. Lipschitz’s page linked to a post from Markdown guru Brett Terpstra

    In it, Terpstra uploaded an mdimporter fix to address these Spotlight/Markdown problems

    Download that ZIP archive and uncompress it

  2. Move Markdown.mdimporter to /Library/Spotlight

    Put the mdimporter here
    Put the mdimporter here

    This is important: Don’t move it to the “user” directory as Lipschitz suggests (~/Library/Spotlight)—put it in the System’s Library folder (/Library/Spotlight) as I’ve detailed above

  3. Open and run the following command:

    mdimport -r /Library/Spotlight/Markdown.mdimporter
  4. You could wait for Spotlight to fix itself. However, for impatient types (myself included), go ahead and force Spotlight to reindex:[1]

    And done:


Unsurprisingly, I fixed this annoying error only after I spent weeks pushing TheOverAnalyzed toward a state of semantic HTML zen.


In other news, I ran every single page through the W3C’s validator to make sure my site was as validated as it could be. The validator still thinks I need section headings for footnote sections (<section class="footnotes">), but I can’t do that until I learn more JavaScript. And then there’s the Safari 9+'s “Pinned Tab” implementation using mask-icon and color attributes—that’s still not officially supported by the HTML5 standard. But that’s pretty good for a web design newbie like myself.

Now, onto more website fiddling.

  1. You could also force Spotlight to reindex only the volume/folder containing the Markdown files by appending the path like so:

    sudo mdutil -E /Volumes/Macintosh\ HD/Users/Anthony/Websites/TheOverAnalyzed/posts/

    This isn’t useful if you have Markdown files all over the place (as I do). If you’re like me, just reindex the whole drive.