Markdown integrity check

Use case or problem

I like to keep my notes in reasonable working order, but I make mistakes. It would be nice to have a pane that shows issues that Obsidian notices while parsing.

This could be shown in the file browser as a warning dot with a mouseover, for example (and propagate to the parent directory.

Things like:

  • Front-matter uses = instead of : and the Yaml can not be parsed right.
  • LaTeX throws an error (mismatching something or other).
  • [[other|heading]] type links where the file exists but the heading can not be found.
  • other things that show up. It seems like they are elegantly hidden, but I’d like to see them for all the files, so I can “clean up” (and distract myself from doing the real work).
  • Flag files that contain whitespace only
  • Flag files that are not linked to and do not contain any links
  • Flag dangling UIDs that are no longer referenced
  • Maybe: Unsupported frontmatter tags (“alas” may be a misspelling of “alias”, then the alias is not working).
  • Maybe: Broken external links (http etc) to keep the brain from rotting. Maybe auto updating 308 permanent redirects, even.

There is at least 1 markdown linter here: https://github.com/markdownlint/markdownlint but that’s probably overkill.

Proposed solution

A right-hand pane that shows all errors, similar to other IDEs. (Obsidian, an IDE for Ideas).

Current workaround (optional)

Click through the pages and see if everything looks OK. Run command-line tools.

6 Likes

Can anyone recommend a good linter that aligns with Obsidian’s flavor of Markdown?

Google says these might be good, but I haven’t tried…

  1. DavidAnson/markdownlint (★2.3k)

  2. markdownlint/markdownlint (★1k)

  3. remarkjs/remark-lint (★707)

1 Like

This would be a nice idea, but such a facility would have to be carefully executed through a combination of selectivity and management of processing constraints

Selectivity

Some of the checks are no-brainers (we’d like to know if there’s a Latex error rather than it simply not working) but some are in a gray area. For example:

I use the heading notation to represent edge types with colon as a metacharacter:

[[George#:parentof]]

in building a semantic network. The notation is benign to Obsidian; it just links to the whole note since the heading isn’t there. This allows me to do some analysis in Obsidian via graph search filters, and a lot of analysis outside of Obsidian. If we could not selectively turn on or off each check, all of my semantic network links would be flagged as an error.

Another good example:

I’ve noticed that a bunch of people in the community rely on backlinks as a form of tag or categorization:

[[recipe]] [[thyme]] [[basil]]

so that, in this example, the person can easily ask a question such as “Show me all of the recipes that can make use of basil,” and this would be the backlink list for the note “basil”. Yet, all of these notes are blank, and would be flagged as an error.

In a nutshell, some “errors” are not errors.

Management of processing constraints

The sum-total of these checks is very resource heavy, and the features could probably be separated into different contexts. For example, linting checks for “external” languages like Latex could be done when the note is visited. You can’t fix the problem until you visit the note, and since there’s no apparent problem until you do so, this seems to me to be the best time to check.

Edit: typo

I try to write as simple as possible Markdown. These are my considerations:

  • CommonMark and GitHub Flavored Markdown (GFM) additions are inside my toolkit.
  • I do not to use some features like $LaTeX math$$, [^Footnotes] or [[Internal links]]. But I can’t live without #tags.
  • ==Highlight== is great but not having an almost-standardized syntax dicourages me from using it.

After editing a note in Obsidian, I open vscode and review it using David Anson’s markdownlint extension. The default rules are usually in-sync with my ideas. Nevertheless, it’s possible to tweak some of them or disable any that I don’t wish to follow.

I hope my experience is useful to make the decision. But it’s a hard one because of the different Markdown tastes Obsidian supports.

I think this feature of “Configurable markdown linting” would be very useful. I’m writing a lot of technical documentation in VS Code with markdownlint extension, so I’m used to just pressing “Save” and seeing everything nicely formatted, especially tables.
Screenshot-20210216154922-532x303 Screenshot-20210216154929-446x309

In the meantime I will configure a script to run markdownlint on my vault, but it would have been so nice to have it built-in.