Merge pull request #4568 from magento/ds_lint-md

Add markdown linting

Author: dshevtsov

.mdlrc

@@ -0,0 +1 @@
+style '_checks/md_style'

Gemfile

@@ -10,6 +10,7 @@ gem 'wdm', platform: :mswin
 
 group :test do
   gem 'html-proofer'
+  gem 'mdl'
   gem 'launchy'
 end
 

Gemfile.lock

@@ -106,9 +106,16 @@ GEM
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
       ruby_dep (~> 1.2)
+    mdl (0.5.0)
+      kramdown (~> 1.12, >= 1.12.0)
+      mixlib-cli (~> 1.7, >= 1.7.0)
+      mixlib-config (~> 2.2, >= 2.2.1)
     mercenary (0.3.6)
     mini_portile2 (2.3.0)
     minitest (5.11.3)
+    mixlib-cli (1.7.0)
+    mixlib-config (2.2.18)
+      tomlrb
     multipart-post (2.1.1)
     netrc (0.11.0)
     nokogiri (1.8.5)
@@ -137,6 +144,7 @@ GEM
       faraday (> 0.8, < 2.0)
     thor (0.20.3)
     thread_safe (0.3.6)
+    tomlrb (1.2.8)
     typhoeus (1.3.1)
       ethon (>= 0.9.0)
     tzinfo (1.2.5)
@@ -166,6 +174,7 @@ DEPENDENCIES
   jekyll-sitemap
   jekyll-titles-from-headings
   launchy
+  mdl
   wdm
   whatsup_github
 

Rakefile

@@ -62,7 +62,7 @@ desc 'Pull docs from external repositories'
 task init: %w[multirepo:init]
 
 desc 'Run checks (image optimization).'
-task check: %w[check:image_optim] 
+task check: %w[check:image_optim check:mdl] 
 
 desc 'Generate data for the weekly digest.'
 task :whatsnew do

_checks/md-check-hook.rb

@@ -0,0 +1,19 @@
+# This Jekyll hook runs Markdown linter (https://github.com/markdownlint/markdownlint)
+# on .md files that git tracks as 'modified' ('git ls-files -m').
+# '_checks/md_style' sets a style (https://github.com/markdownlint/markdownlint/blob/master/docs/creating_styles.md)
+# that is a set of rules to be applied when linting (https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md).
+# '.mdlrc' sets linting configuration (https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md).
+#
+# The plugin runs in serving mode only.
+#
+Jekyll::Hooks.register :site, :post_write do |site|
+  next unless site.config['serving']
+  staged_files = `git ls-files -m`.split("\n")
+  staged_md_files = staged_files.select { |file| File.extname(file) == '.md' }
+  next if staged_md_files.empty?
+  puts 'Checking Markdown syntax...'.blue
+  staged_md_files_as_a_string = staged_md_files.join(' ')
+  report = `bin/mdl #{staged_md_files_as_a_string}`
+  puts report.yellow
+  puts 'The style is defined in _checks/md_style'.yellow
+end

_checks/md_style

@@ -0,0 +1,41 @@
+# Approved style
+rule 'MD001'
+exclude_rule 'MD002'
+rule 'MD003', :style => :atx
+rule 'MD004'
+rule 'MD005'
+rule 'MD006'
+rule 'MD009'
+rule 'MD010'
+rule 'MD011'
+rule 'MD012'
+exclude_rule 'MD013'
+exclude_rule 'MD014'
+rule 'MD018'
+rule 'MD019'
+exclude_rule 'MD020'
+exclude_rule 'MD021'
+rule 'MD022'
+rule 'MD023'
+rule 'MD024', :allow_different_nesting => true
+rule 'MD025'
+
+# The following rules still require Docs team review and approval
+exclude_rule 'MD007'
+exclude_rule 'MD026'
+exclude_rule 'MD027'
+exclude_rule 'MD028'
+exclude_rule 'MD029'
+exclude_rule 'MD030'
+exclude_rule 'MD031'
+exclude_rule 'MD032'
+exclude_rule 'MD033'
+exclude_rule 'MD034'
+exclude_rule 'MD035'
+exclude_rule 'MD036'
+exclude_rule 'MD037'
+exclude_rule 'MD038'
+exclude_rule 'MD039'
+exclude_rule 'MD040'
+exclude_rule 'MD041'
+exclude_rule 'MD046'

bin/mdl

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'mdl' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("mdl", "mdl")

rakelib/check.rake

@@ -11,4 +11,19 @@ namespace :check do
     end
     system "bin/image_optim --no-pngout --no-svgo --recursive #{path}"
   end
+
+  desc 'Check Markdown syntax in modified files or in a particular file or directory by path (e.g. path=mftf)'
+  task :mdl do
+    path = ENV['path']
+    unless path
+      staged_files = `git ls-files -m`.split("\n")
+      staged_md_files = staged_files.select { |file| File.extname(file) == '.md' }
+      abort 'Cannot find any modified .md files.'.magenta if staged_md_files.empty?
+      path = staged_md_files.join(' ')
+    end
+    puts 'Running Markdown linter ...'.magenta
+    report = `bin/mdl #{path}`
+    puts report.yellow
+    puts 'The rules are defined in _checks/md_style'.magenta
+  end
 end