mdl 0.2.1 → 0.3.0

data/docs/configuration.md

@@ -1,7 +1,8 @@
 # Mdl configuration
 
 Markdownlint has several options you can configure both on the command line,
-or in markdownlint's configuration file: `.mdlrc` in your home directory.
+or in markdownlint's configuration file: `.mdlrc`, first looked for from the
+working directory, then in your home directory.
 While markdownlint will work perfectly well out of the box, this page
 documents some of the options you can change to suit your needs.
 
@@ -72,3 +73,17 @@ might choose 72 characters, and another might have no line length limit at all
 
 Note: the value for `style_name` must either end with `.rb` or have `/` in it
 in order to tell `mdl` to look for a custom style, and not a built-in style.
+
+Rulesets - Load a custom ruleset file. This option allows you to load custom
+rules in addition to those included with markdownlint.
+
+* Command line: `-u ruleset.rb,ruleset2.rb`, `--rules ruleset.rb,ruleset2.rb`
+* Config file: `rulesets 'ruleset.rb', 'ruleset2.rb'`
+* Default: Don't load any additional rulesets
+
+No default ruleset - Skip loading the default ruleset file included with
+markdownlint. Use this option if you only want to load custom rulesets.
+
+* Command line: `-d`, `--skip-default-ruleset`
+* Config file: `skip_default_ruleset true`
+* Default: Load the default ruleset.

data/docs/creating_rules.md

@@ -5,6 +5,7 @@ like:
 
     rule "MD000", "Rule description" do
       tags :foo, :bar
+      aliases 'rule-name'
       params :style => :foo
       check do |doc|
         # check code goes here
@@ -26,6 +27,12 @@ checks whitespace usage in a document, you can add the `:whitespace` tag, and
 users who don't care about whitespace can exclude that tag on the command line
 or in style files.
 
+You can also specify aliases for the rule, which can be used to refer to the
+rule with a human-readable name rather than MD000. To do this, add then with
+the 'aliases' directive. Whenever you refer to a rule, such as for
+including/excluding in the configuration or in style files, you can use an
+alias for the rule instead of its ID.
+
 After that, any parameters the rule takes are specified. If your rule checks
 for a specific number of things, or if you can envision multiple variants of
 the same rule, then you should add parameters to allow your rule to be

data/lib/mdl.rb

@@ -9,16 +9,27 @@ require 'mdl/version'
 require 'kramdown'
 
 module MarkdownLint
-  def self.run
+  def self.run(argv=ARGV)
     cli = MarkdownLint::CLI.new
-    cli.run
-    rules = RuleSet.load_default
+    cli.run(argv)
+    ruleset = RuleSet.new
+    unless Config[:skip_default_ruleset]
+      ruleset.load_default
+    end
+    unless Config[:rulesets].nil?
+      Config[:rulesets].each do |r|
+        ruleset.load(r)
+      end
+    end
+    rules = ruleset.rules
     Style.load(Config[:style], rules)
     # Rule option filter
     if Config[:rules]
-      rules.select! {|r| Config[:rules][:include].include?(r) } \
+      rules.select! {|r, v| Config[:rules][:include].include?(r) or
+                     !(Config[:rules][:include] & v.aliases).empty? } \
         unless Config[:rules][:include].empty?
-      rules.select! {|r| not Config[:rules][:exclude].include?(r) } \
+      rules.select! {|r, v| not Config[:rules][:exclude].include?(r) and
+                     (Config[:rules][:exclude] & v.aliases).empty? } \
         unless Config[:rules][:exclude].empty?
     end
     # Tag option filter
@@ -33,7 +44,9 @@ module MarkdownLint
       puts "Enabled rules:"
         rules.each do |id, rule|
           if Config[:verbose]
-            puts "#{id} (#{rule.tags.join(', ')}) - #{rule.description}"
+            puts "#{id} (#{rule.aliases.join(', ')}) [#{rule.tags.join(', ')}] - #{rule.description}"
+          elsif Config[:show_aliases]
+            puts "#{rule.aliases.first || id} - #{rule.description}"
           else
             puts "#{id} - #{rule.description}"
           end
@@ -46,10 +59,10 @@ module MarkdownLint
       if Dir.exist?(filename)
         if Config[:git_recurse]
           Dir.chdir(filename) do
-            cli.cli_arguments[i] = %x(git ls-files '*.md').split("\n")
+            cli.cli_arguments[i] = %x(git ls-files '*.md' '*.markdown').split("\n")
           end
         else
-          cli.cli_arguments[i] = Dir["#{filename}/**/*.md"]
+          cli.cli_arguments[i] = Dir["#{filename}/**/*.{md,markdown}"]
         end
       end
     end
@@ -72,7 +85,11 @@ module MarkdownLint
         next if error_lines.nil? or error_lines.empty?
         status = 1
         error_lines.each do |line|
-          puts "#{filename}:#{line}: #{id} #{rule.description}"
+          if Config[:show_aliases]
+            puts "#{filename}:#{line}: #{rule.aliases.first || id} #{rule.description}"
+          else
+            puts "#{filename}:#{line}: #{id} #{rule.description}"
+          end
         end
       end
     end

data/lib/mdl/cli.rb

@@ -4,13 +4,21 @@ module MarkdownLint
   class CLI
     include Mixlib::CLI
 
+    CONFIG_FILE = '.mdlrc'
+
     banner "Usage: #{File.basename($0)} [options] [FILE.md|DIR ...]"
 
+    option :show_aliases,
+      :short => '-a',
+      :long => '--[no-]show-aliases',
+      :description => 'Show rule alias instead of rule ID when viewing rules',
+      :boolean => true
+
     option :config_file,
       :short => '-c',
       :long => '--config FILE',
       :description => 'The configuration file to use',
-      :default => '~/.mdlrc'
+      :default => "#{CONFIG_FILE}"
 
     option :verbose,
       :short => '-v',
@@ -53,6 +61,18 @@ module MarkdownLint
       :boolean => true,
       :description => "Only process files known to git when given a directory"
 
+    option :rulesets,
+      :short => '-u',
+      :long => '--rulesets RULESET1,RULESET2',
+      :proc => Proc.new { |v| v.split(',') },
+      :description => "Specify additional ruleset files to load"
+
+    option :skip_default_ruleset,
+      :short => '-d',
+      :long => '--skip-default-ruleset',
+      :boolean => true,
+      :description => "Don't load the default markdownlint ruleset"
+
     option :help,
       :on => :tail,
       :short => '-h',
@@ -73,9 +93,20 @@ module MarkdownLint
 
     def run(argv=ARGV)
       parse_options(argv)
+
       # Load the config file if it's present
-      filename = File.expand_path(config[:config_file])
-      MarkdownLint::Config.from_file(filename) if File.exists?(filename)
+      filename = CLI.probe_config_file(config[:config_file])
+      # Only fall back to ~/.mdlrc if we are using the default value for -c
+      if filename.nil? and config[:config_file] == CONFIG_FILE
+        filename = File.expand_path("~/#{CONFIG_FILE}")
+      end
+
+      if not filename.nil? and File.exist?(filename)
+        MarkdownLint::Config.from_file(filename)
+        if config[:verbose]
+          puts "Loaded config from #{filename}"
+        end
+      end
 
       # Put values in the config file
       MarkdownLint::Config.merge!(config)
@@ -99,13 +130,33 @@ module MarkdownLint
       if parts.class == String
         parts = parts.split(',')
       end
-      inc = parts.select{|p| not p.start_with?('~')}
-      exc = parts.select{|p| p.start_with?('~')}.map{|p| p[1..-1]}
-      if to_sym
-        inc.map!{|p| p.to_sym}
-        exc.map!{|p| p.to_sym}
+      if parts.class == Array
+        inc = parts.select{|p| not p.start_with?('~')}
+        exc = parts.select{|p| p.start_with?('~')}.map{|p| p[1..-1]}
+        if to_sym
+          inc.map!{|p| p.to_sym}
+          exc.map!{|p| p.to_sym}
+        end
+        {:include => inc, :exclude => exc}
+      else
+        # We already converted the string into a list of include/exclude
+        # pairs, so just return as is
+        parts
+      end
+    end
+
+    def self.probe_config_file(path)
+      # Probe up only for plain filenames
+      if path != File.basename(path)
+        return File.expand_path(path)
+      end
+
+      # Look for a file up from the working dir
+      Pathname.new(path).ascend do |p|
+        config_file = p.join(CONFIG_FILE)
+        return config_file if File.exist?(CONFIG_FILE)
       end
-      {:include => inc, :exclude => exc}
+      nil
     end
   end
 end

data/lib/mdl/doc.rb

@@ -217,6 +217,10 @@ module MarkdownLint
       matches = []
       find_type_elements_except(:text, exclude_nested).each do |e|
         first_line = e.options[:location]
+        # We'll error out if kramdown doesn't have location information for
+        # the current element. It's better to just not match in these cases
+        # rather than crash.
+        next if first_line.nil?
         lines = e.value.split("\n")
         lines.each_with_index do |l, i|
           matches << first_line + i if re.match(l)
@@ -242,7 +246,7 @@ module MarkdownLint
       lines = element.children.map { |e|
         if e.type == :text
           e.value
-        elsif [:strong, :em, :p].include?(e.type)
+        elsif [:strong, :em, :p, :codespan].include?(e.type)
           extract_text(e, prefix).join("\n")
         elsif e.type == :smart_quote
           quotes[e.value]

data/lib/mdl/rules.rb

@@ -1,5 +1,6 @@
 rule "MD001", "Header levels should only increment by one level at a time" do
   tags :headers
+  aliases 'header-increment'
   check do |doc|
     headers = doc.find_type(:header)
     old_level = nil
@@ -16,6 +17,7 @@ end
 
 rule "MD002", "First header should be a h1 header" do
   tags :headers
+  aliases 'first-header-h1'
   check do |doc|
     first_header = doc.find_type(:header).first
     [first_header[:location]] if first_header and first_header[:level] != 1
@@ -26,6 +28,7 @@ rule "MD003", "Header style" do
   # Header styles are things like ### and adding underscores
   # See http://daringfireball.net/projects/markdown/syntax#header
   tags :headers
+  aliases 'header-style'
   # :style can be one of :consistent, :atx, :atx_closed, :setext
   params :style => :consistent
   check do |doc|
@@ -38,14 +41,22 @@ rule "MD003", "Header style" do
       else
         doc_style = @params[:style]
       end
-      headers.map { |h| doc.element_linenumber(h) \
-                    if doc.header_style(h) != doc_style }.compact
+      if doc_style == :setext_with_atx
+        headers.map { |h| doc.element_linenumber(h) \
+                      unless doc.header_style(h) == :setext or \
+                        (doc.header_style(h) == :atx and \
+                         h.options[:level] > 2) }.compact
+      else
+        headers.map { |h| doc.element_linenumber(h) \
+                      if doc.header_style(h) != doc_style }.compact
+      end
     end
   end
 end
 
 rule "MD004", "Unordered list style" do
   tags :bullet, :ul
+  aliases 'ul-style'
   # :style can be one of :consistent, :asterisk, :plus, :dash
   params :style => :consistent
   check do |doc|
@@ -67,6 +78,7 @@ end
 
 rule "MD005", "Inconsistent indentation for list items at the same level" do
   tags :bullet, :ul, :indentation
+  aliases 'list-indent'
   check do |doc|
     bullets = doc.find_type(:li)
     errors = []
@@ -88,6 +100,7 @@ rule "MD006", "Consider starting bulleted lists at the beginning of the line" do
   # Starting at the beginning of the line means that indendation for each
   # bullet level can be identical.
   tags :bullet, :ul, :indentation
+  aliases 'ul-start-left'
   check do |doc|
     doc.find_type(:ul, false).select{
       |e| doc.indent_for(doc.element_line(e)) != 0 }.map{ |e| e[:location] }
@@ -96,6 +109,7 @@ end
 
 rule "MD007", "Unordered list indentation" do
   tags :bullet, :ul, :indentation
+  aliases 'ul-indent'
   params :indent => 2
   check do |doc|
     indents = []
@@ -115,6 +129,7 @@ end
 
 rule "MD009", "Trailing spaces" do
   tags :whitespace
+  aliases 'no-trailing-spaces'
   params :br_spaces => 0
   check do |doc|
     errors = doc.matching_lines(/\s$/)
@@ -127,6 +142,7 @@ end
 
 rule "MD010", "Hard tabs" do
   tags :whitespace, :hard_tab
+  aliases 'no-hard-tabs'
   check do |doc|
     doc.matching_lines(/\t/)
   end
@@ -134,6 +150,7 @@ end
 
 rule "MD011", "Reversed link syntax" do
   tags :links
+  aliases 'no-reversed-links'
   check do |doc|
     doc.matching_text_element_lines(/\([^)]+\)\[[^\]]+\]/)
   end
@@ -141,6 +158,7 @@ end
 
 rule "MD012", "Multiple consecutive blank lines" do
   tags :whitespace, :blank_lines
+  aliases 'no-multiple-blanks'
   check do |doc|
     # Every line in the document that is part of a code block. Blank lines
     # inside of a code block are acceptable.
@@ -156,14 +174,31 @@ end
 
 rule "MD013", "Line length" do
   tags :line_length
-  params :line_length => 80
+  aliases 'line-length'
+  params :line_length => 80, :code_blocks => true, :tables => true
   check do |doc|
-    doc.matching_lines(/^.{#{@params[:line_length]}}.*\s/)
+    # Every line in the document that is part of a code block.
+    codeblock_lines = doc.find_type_elements(:codeblock).map{
+      |e| (doc.element_linenumber(e)..
+           doc.element_linenumber(e) + e.value.count('\n') - 1).to_a }.flatten
+    # Every line in the document that is part of a table.
+    locations = doc.elements
+                .map { |e| [e.options[:location], e] }
+                .reject { |l, _| l.nil? }
+    table_lines = locations.map.with_index {
+      |(l, e), i| (i + 1 < locations.size ?
+                   (l..locations[i+1].first - 1) :
+                   (l..doc.lines.count)).to_a if e.type == :table }.flatten
+    overlines = doc.matching_lines(/^.{#{@params[:line_length]}}.*\s/)
+    overlines -= codeblock_lines unless params[:code_blocks]
+    overlines -= table_lines unless params[:tables]
+    overlines
   end
 end
 
 rule "MD014", "Dollar signs used before commands without showing output" do
   tags :code
+  aliases 'commands-show-output'
   check do |doc|
     doc.find_type_elements(:codeblock).select{
       |e| not e.value.empty? and
@@ -174,6 +209,7 @@ end
 
 rule "MD018", "No space after hash on atx style header" do
   tags :headers, :atx, :spaces
+  aliases 'no-missing-space-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx and doc.element_line(h).match(/^#+[^#\s]/)
@@ -183,6 +219,7 @@ end
 
 rule "MD019", "Multiple spaces after hash on atx style header" do
   tags :headers, :atx, :spaces
+  aliases 'no-multiple-space-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx and doc.element_line(h).match(/^#+\s\s/)
@@ -192,6 +229,7 @@ end
 
 rule "MD020", "No space inside hashes on closed atx style header" do
   tags :headers, :atx_closed, :spaces
+  aliases 'no-missing-space-closed-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx_closed \
@@ -203,6 +241,7 @@ end
 
 rule "MD021", "Multiple spaces inside hashes on closed atx style header" do
   tags :headers, :atx_closed, :spaces
+  aliases 'no-multiple-space-closed-atx'
   check do |doc|
     doc.find_type_elements(:header).select do |h|
       doc.header_style(h) == :atx_closed \
@@ -214,6 +253,7 @@ end
 
 rule "MD022", "Headers should be surrounded by blank lines" do
   tags :headers, :blank_lines
+  aliases 'blanks-around-headers'
   check do |doc|
     errors = []
     doc.find_type_elements(:header).each do |h|
@@ -257,6 +297,7 @@ end
 
 rule "MD023", "Headers must start at the beginning of the line" do
   tags :headers, :spaces
+  aliases 'header-start-left'
   check do |doc|
     errors = []
     # The only type of header with spaces actually parsed as such is setext
@@ -289,6 +330,7 @@ end
 
 rule "MD024", "Multiple headers with the same content" do
   tags :headers
+  aliases 'no-duplicate-header'
   check do |doc|
     header_content = Set.new
     doc.find_type(:header).select do |h|
@@ -299,6 +341,7 @@ end
 
 rule "MD025", "Multiple top level headers in the same document" do
   tags :headers
+  aliases 'single-h1'
   check do |doc|
     headers = doc.find_type(:header).select { |h| h[:level] == 1 }
     if not headers.empty? and doc.element_linenumber(headers[0]) == 1
@@ -309,6 +352,7 @@ end
 
 rule "MD026", "Trailing punctuation in header" do
   tags :headers
+  aliases 'no-trailing-punctuation'
   params :punctuation => '.,;:!?'
   check do |doc|
     doc.find_type(:header).select {
@@ -319,6 +363,7 @@ end
 
 rule "MD027", "Multiple spaces after blockquote symbol" do
   tags :blockquote, :whitespace, :indentation
+  aliases 'no-multiple-space-blockquote'
   check do |doc|
     errors = []
     doc.find_type_elements(:blockquote).each do |e|
@@ -335,6 +380,7 @@ end
 
 rule "MD028", "Blank line inside blockquote" do
   tags :blockquote, :whitespace
+  aliases 'no-blanks-blockquote'
   check do |doc|
     def check_blockquote(errors, elements)
       prev = [nil, nil, nil]
@@ -358,6 +404,7 @@ end
 
 rule "MD029", "Ordered list item prefix" do
   tags :ol
+  aliases 'ol-prefix'
   # Style can be :one or :ordered
   params :style => :one
   check do |doc|
@@ -379,6 +426,7 @@ end
 
 rule "MD030", "Spaces after list markers" do
   tags :ol, :ul, :whitespace
+  aliases 'list-marker-space'
   params :ul_single => 1, :ol_single => 1, :ul_multi => 1, :ol_multi => 1
   check do |doc|
     errors = []
@@ -400,14 +448,18 @@ end
 
 rule "MD031", "Fenced code blocks should be surrounded by blank lines" do
   tags :code, :blank_lines
+  aliases 'blanks-around-fences'
   check do |doc|
     errors = []
     # Some parsers (including kramdown) have trouble detecting fenced code
     # blocks without surrounding whitespace, so examine the lines directly.
     in_code = false
+    fence = nil
     lines = [ "" ] + doc.lines + [ "" ]
     lines.each_with_index do |line, linenum|
-      if line.strip.match(/^(```|~~~)/)
+      line.strip.match(/^(`{3,}|~{3,})/)
+      if $1 and (not in_code or $1.slice(0, fence.length) == fence)
+        fence = in_code ? nil : $1
         in_code = !in_code
         if (in_code and not lines[linenum - 1].empty?) or
            (not in_code and not lines[linenum + 1].empty?)
@@ -421,12 +473,14 @@ end
 
 rule "MD032", "Lists should be surrounded by blank lines" do
   tags :bullet, :ul, :ol, :blank_lines
+  aliases 'blanks-around-lists'
   check do |doc|
     errors = []
     # Some parsers (including kramdown) have trouble detecting lists
     # without surrounding whitespace, so examine the lines directly.
     in_list = false
     in_code = false
+    fence = nil
     prev_line = ""
     doc.lines.each_with_index do |line, linenum|
       if not in_code
@@ -438,7 +492,9 @@ rule "MD032", "Lists should be surrounded by blank lines" do
         end
         in_list = list_marker
       end
-      if line.strip.match(/^(```|~~~)/)
+      line.strip.match(/^(`{3,}|~{3,})/)
+      if $1 and (not in_code or $1.slice(0, fence.length) == fence)
+        fence = in_code ? nil : $1
         in_code = !in_code
         in_list = false
       end
@@ -450,6 +506,7 @@ end
 
 rule "MD033", "Inline HTML" do
   tags :html
+  aliases 'no-inline-html'
   check do |doc|
     doc.element_linenumbers(doc.find_type(:html_element))
   end
@@ -457,6 +514,7 @@ end
 
 rule "MD034", "Bare URL used" do
   tags :links, :url
+  aliases 'no-bare-urls'
   check do |doc|
     doc.matching_text_element_lines(/https?:\/\//)
   end
@@ -464,6 +522,7 @@ end
 
 rule "MD035", "Horizontal rule style" do
   tags :hr
+  aliases 'hr-style'
   params :style => :consistent
   check do |doc|
     hrs = doc.find_type(:hr)
@@ -482,6 +541,7 @@ end
 
 rule "MD036", "Emphasis used instead of a header" do
   tags :headers, :emphasis
+  aliases 'no-emphasis-as-header'
   check do |doc|
     # We are looking for a paragraph consisting entirely of emphasized
     # (italic/bold) text.
@@ -492,6 +552,7 @@ end
 
 rule "MD037", "Spaces inside emphasis markers" do
   tags :whitespace, :emphasis
+  aliases 'no-space-in-emphasis'
   check do |doc|
     # Kramdown doesn't parse emphasis with spaces, which means we can just
     # look for emphasis patterns inside regular text with spaces just inside
@@ -503,6 +564,7 @@ end
 
 rule "MD038", "Spaces inside code span elements" do
   tags :whitespace, :code
+  aliases 'no-space-in-code'
   check do |doc|
     # We only want to check single line codespan elements and not fenced code
     # block that happen to be parsed as code spans.
@@ -513,6 +575,7 @@ end
 
 rule "MD039", "Spaces inside link text" do
   tags :whitespace, :links
+  aliases 'no-space-in-links'
   check do |doc|
     doc.element_linenumbers(doc.find_type_elements(:a).select{|e|
       e.children[0].type == :text and
@@ -523,6 +586,7 @@ end
 
 rule "MD040", "Fenced code blocks should have a language specified" do
   tags :code, :language
+  aliases 'fenced-code-language'
   check do |doc|
     # Kramdown parses code blocks with language settings as code blocks with
     # the class attribute set to language-languagename.
@@ -531,3 +595,13 @@ rule "MD040", "Fenced code blocks should have a language specified" do
         not doc.element_line(i).start_with?("    ")})
   end
 end
+
+rule "MD041", "First line in file should be a top level header" do
+  tags :headers
+  aliases 'first-line-h1'
+  check do |doc|
+    first_header = doc.find_type(:header).first
+    [1] if first_header.nil? or first_header[:location] != 1 \
+      or first_header[:level] != 1
+  end
+end