Marc d'Ouane

a beautiful, epic Markdown linter

Install the gem and add to the application's Gemfile by executing:

bundle add marcdouane

If bundler is not being used to manage dependencies, install the gem by executing:

gem install marcdouane

Checking a file with default rules:

marcdouane check some-file.md

For the complete tour just use

marcdouane
marcdouane check --help

Some rules have settings (see lib/marcdouane/rules.rb for now). These settings can be overriden with a YAML config file that resembles the Rubocop config:

LineLength:
  maximum_line_length: 90 # which is utter madness

Marcdouane uses a very common output format:

filename:lineno: [ErrorName] error message

(flycheck-define-checker marcdouane
  "A Markdown linter using marcdouane

See URL `https://github.com/freesteph/marcdouane/'."
  :command ("marcdouane" "check" source)
  :error-patterns
  ((error line-start (file-name) ":" line ": " (message) line-end))
  :error-explainer (lambda (err)
                     (let ((str (flycheck-error-message err)))
                       (when (string-match "\\[\\([^]]+\\)\\]" str)
                         (let* ((class (match-string 1 str)))
                           (shell-command-to-string (format "ri --format=markdown --no-pager Marcdouane::Rules::%s" class))))))
  :modes markdown-mode)

(add-to-list 'flycheck-checkers 'marcdouane)

I'm doing it

You can generate a new rule with bundle exec thor generate_rule YourRuleName which will write the class file, require it and add a new test-case for it.

A rule must inherit Marcdouane::Rule. It must answer to check! and call error! to signal a faulty line. The message defaults to the class's ERROR_MESSAGE but can be overriden through the message parameter. The line-number is 0-indexed. Example:

class CheckAnglois < Marcdouane::Rule
  ERROR_MESSAGE = "Do not mention the English"

  def check!
    File
      .read(file)
      .lines
      .each_with_index do |line, index|
      error!(index) if line =~ /anglois/
    end
  end
end

This will get the CLI to output:

<filename>:<line_number>: [CheckAnglois] Do not mention the English

All rules are expected to be tested via the extensive test suite in features/rules.features, using Cucumber and Aruba like such:

Feature: Built-in Markdown Rules
  # [...]

  Rule: Don't mention the English
    Example: It fails when the English are mentioned
      Given a file named "foo.md" with:
        """
        # Tout va bien
        Pas d'anglois à l'horizon
        """
      When I run `marcdouane check "foo.md"`
      Then it should fail with:
        """
        foo.md:2: Don't mention the English
        """

    Example: It passes when the English are not mentioned
      Given a file named "foo.md" with:
        """
        # Tout va bien
        Quelques voix dans la tête mais tranquille
        """
      When I run `marcdouane check "foo.md"`
      Then it should pass

Bug reports and pull requests are welcome on GitHub at https://github.com/freesteph/marcdouane.

The gem is available as open source under the terms of the MIT License.