rubocop-md 2.0.4 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3daa631b2f266f022b572d333bca39c035fca85c6cd3616c855f3cd796f04f7
-  data.tar.gz: 3e78b24aee5905d444d632d7ff92f348f1ad6bbf1c8747a0c149be1373ec8a6f
+  metadata.gz: ac56ce2479d67dd646a069af3e135366bef0eaf66eddf47d607e9d8248d9b738
+  data.tar.gz: 727d15a419748305dc44918c85f14db8116d46864ff91ee9c39b10fc2996938b
 SHA512:
-  metadata.gz: 02ed290d0f3cbfcb6d8a28f762ff7ee9d2382f391b1b6464a57f9354cbd481cfe8967bd4e1274b70ed97c1526832029efe8e4a997f7477dc3b2256c2e67e54dd
-  data.tar.gz: cd2fdbe1a09b41dcf83ca2aa63edb827adfae08259c9a48b6a21e59710a8c0feffd9ec3ed7e418eb720904764e5ca69f69855ba9eadaae1b42d6a61ef66e7a3b
+  metadata.gz: df438f27e7a0e7210dc7c80b6169b7bfef9adf43af3433ceff01b324dc0693935b20a5c9c6a76166015b40443cb387924bc423796ae9621b82ef0a460ff169d4
+  data.tar.gz: d133ccb642a94601be04fa918b5d6c1d5ff64ffc3d175fa3888386172c897b8c82c0b6a0ea26c872127b13e9b4b1fb022f206df5fb332007e95fe118b9ea8b55

data/CHANGELOG.md

@@ -1,83 +1,101 @@
 # Change log
 
-## master (unreleased)
+## 3.0.0 (2026-11-06)
+
+- Add opt-in `Markdown/Syntax` to report parser warnings as standard RuboCop offenses instead of writing them separately to stderr ([#50](https://github.com/rubocop/rubocop-md/pull/50), [@dblock][], [@Copilot][]).
+- Exclude leading YAML front matter from Ruby snippet extraction without changing the original source or offense locations ([#57](https://github.com/rubocop/rubocop-md/pull/57), [@dblock][], [@Copilot][]).
+- Preserve the original Markdown buffer for prose plugins and combine original-source edits with Ruby snippet corrections ([#55](https://github.com/rubocop/rubocop-md/pull/55), [@dblock][], [@Copilot][]).
+- Replace standalone regex-based snippet extraction with a reusable Markdown document parser, supporting tilde fences, indented code, and code blocks inside lists and blockquotes while preserving their source prefixes during autocorrection ([#51](https://github.com/rubocop/rubocop-md/pull/51), [@dblock][], [@Copilot][]).
+- Fix false indentation offenses in and after list-nested code blocks ([#28](https://github.com/rubocop/rubocop-md/issues/28), [#51](https://github.com/rubocop/rubocop-md/pull/51), [@dblock][], [@Copilot][]).
+- Fix `rubocop:disable`, `rubocop:todo`, and `rubocop:enable` directives wrapped in spans or HTML comments outside Ruby code blocks ([#52](https://github.com/rubocop/rubocop-md/pull/52), [@dblock][], [@ocvit][], [@Copilot][]).
 
 ## 2.0.4 (2026-01-28)
 
-- Enable caching when no offenses detected.
+- Enable caching when no offenses detected ([@byroot][]).
 
 ## 2.0.3 (2025-09-30)
 
-- Fix compatibility with RuboCop upstream (`get_processed_source` signature)
+- Fix compatibility with RuboCop upstream (`get_processed_source` signature) ([@Rylan12][]).
 
 ## 2.0.2 (2025-08-20)
 
-- Support metadata in code blocks.
+- Support metadata in code blocks ([@balvig][]).
 
 ## 2.0.1 (2025-04-14)
 
-- Remove `Layout/TrailingBlankLines`.
+- Remove `Layout/TrailingBlankLines` ([@rmm5t][]).
 
 ## 2.0.0 (2025-02-17)
 
-- Migrate to new RuboCop Plugin architecture.
+- Migrate to new RuboCop Plugin architecture ([@koic][]).
 
 ## 1.2.4 (2024-10-16)
 
-- Fix RuboCop warnings.
+- Fix RuboCop warnings ([@koic][]).
 
 ## 1.2.3 (2024-09-12)
 
-- Do no try linting `.mdx` files by default.
+- Do no try linting `.mdx` files by default ([@larouxn][]).
 
 ## 1.2.2 (2023-12-01) ❄️
 
-- Fix analyzing code blocks with backticks.
+- Fix analyzing code blocks with backticks ([@palkan][]).
 
 ## 1.2.1 (2023-10-20)
 
-- Fix incompatibility when loading the plugin from YAML and using other RuboCop options.
+- Fix incompatibility when loading the plugin from YAML and using other RuboCop options ([@prog-supdex][], [@palkan][]).
 
 ## 1.2.0 (2023-01-31)
 
-- Fix parsing compound syntax hints in code snippets.
+- Fix parsing compound syntax hints in code snippets ([@palkan][]).
 
-- Drop Ruby 2.5 support.
+- Drop Ruby 2.5 support ([@palkan][]).
 
 ## 1.1.0 (2022-10-24)
 
-- Ignore offenses in non-code source.
+- Ignore offenses in non-code source ([@palkan][]).
 
 ## 1.0.1 (2020-12-28)
 
-- Exclude `EmptyLineBetweenDefs` for MD files.
+- Exclude `EmptyLineBetweenDefs` for MD files ([@palkan][]).
 
 ## 1.0.0 (2020-12-24)
 
-- Drop Ruby 2.4 support and require RuboCop 1.0.
+- Drop Ruby 2.4 support and require RuboCop 1.0 ([@palkan][]).
 
 ## 0.4.1 (2020-11-05)
 
-- Relax required RuboCop version.
+- Relax required RuboCop version ([@sfeuga][]).
 
 ## 0.4.0 (2020-07-03)
 
-- [#10](https://github.com/rubocop-hq/rubocop-md/pull/10): **Drop Ruby 2.3 support** ([@dominicsayers][])
+- [#10](https://github.com/rubocop-hq/rubocop-md/pull/10): **Drop Ruby 2.3 support** ([@dominicsayers][]).
 
 ## 0.3.2 (2020-03-18)
 
-- [#9](https://github.com/rubocop-hq/rubocop-md/pull/9): Add file extensions for Markdown ([@ybiquitous][])
+- [#9](https://github.com/rubocop-hq/rubocop-md/pull/9): Add file extensions for Markdown ([@ybiquitous][]).
 
 ## 0.3.1 (2019-12-25)
 
-- Upgrade to RuboCop 0.78 ([@palkan][])
+- Upgrade to RuboCop 0.78 ([@palkan][]).
 
 Change the default config to use the new cop names for (e.g., `Layout/LineLength`).
 
 ## 0.3.0 (2019-05-14)
 
-- **Drop Ruby 2.2 support** ([@palkan][])
+- **Drop Ruby 2.2 support** ([@palkan][]).
 
 [@palkan]: https://github.com/palkan
 [@ybiquitous]: https://github.com/ybiquitous
 [@dominicsayers]: https://github.com/dominicsayers
+[@byroot]: https://github.com/byroot
+[@Rylan12]: https://github.com/Rylan12
+[@balvig]: https://github.com/balvig
+[@rmm5t]: https://github.com/rmm5t
+[@koic]: https://github.com/koic
+[@larouxn]: https://github.com/larouxn
+[@prog-supdex]: https://github.com/prog-supdex
+[@sfeuga]: https://github.com/sfeuga
+[@dblock]: https://github.com/dblock
+[@Copilot]: https://github.com/Copilot
+[@ocvit]: https://github.com/ocvit

data/README.md

@@ -5,12 +5,17 @@
 
 Run Rubocop against your Markdown files to make sure that code examples follow style guidelines and have valid syntax.
 
+<br/>
+
+<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="Evil Martians logo" width="22" height="16" /> <b>RuboCop Markdown</b> is built by <b><a href="https://evilmartians.com/">Evil Martians</a></b>, an American design and engineering consultancy for <b>developer tools, AI, and cybersecurity startups</b>.
+
 ## Features
 
 - Analyzes code blocks within Markdown files
-- Shows correct line numbers in output
+- Shows correct source line numbers and columns in output
 - Preserves specified language (i.e., do not try to analyze "\`\`\`sh")
 - **Supports autocorrect 📝**
+- Parses backtick and tilde fences, indented code, and code blocks inside lists and blockquotes
 
 This project was developed to keep [test-prof](https://github.com/test-prof/test-prof) guides consistent with Ruby style guide back in 2017. Since then, many popular Ruby projects adopted it, including:
 
@@ -112,9 +117,34 @@ Lint/Void:
     - '*.md'
 ```
 
-### But if I want to use inline disabling some directive like in classic RuboCop?
+### Code blocks
+
+Markdown is parsed with Kramdown's pure-Ruby GFM parser, retaining compatibility with JRuby. Backtick and tilde fences support language tags and additional metadata, including fences longer than three characters. Code blocks inside lists and blockquotes are supported, and autocorrection preserves their Markdown prefixes even when Ruby edits add or remove lines.
+
+Indented code blocks are treated as unlabeled snippets: they are checked when `Markdown.Autodetect` is enabled and their contents parse as Ruby. Explicitly non-Ruby language tags are always ignored. `Markdown.WarnInvalid` retains its existing behavior for explicitly Ruby-tagged snippets.
+
+Leading YAML front matter, opened with `---` and closed with `---` or `...`, is excluded from snippet extraction so metadata is not mistaken for Ruby code. The original source and offense locations are preserved; unclosed headers and delimiters elsewhere remain ordinary Markdown.
+
+The original Markdown remains available through `processed_source.markdown_document.buffer` for prose plugins such as `rubocop-spellcheck`. `processed_source.buffer` retains the preprocessed Ruby source expected by Ruby cops. Prose ranges can be mapped with `markdown_document.processed_range`; diagnostics and corrections from either buffer retain their original Markdown locations and can be combined in the same run.
+
+### Markdown syntax diagnostics
+
+Enable `Markdown/Syntax` in `.rubocop.yml` to report Kramdown's parser warnings through RuboCop's normal formatters:
+
+```yml
+Markdown/Syntax:
+  Enabled: true
+```
+
+This opt-in cop reports warning-severity offenses for diagnostics such as undefined references and malformed HTML. It does not provide complete Markdown validation or autocorrection. Multiple warnings on the same line are combined into one offense; warnings without a usable location are reported at the start of the file. Normal cop configuration, `--except`, and inline disabling directives apply.
+
+Parser warnings are no longer printed separately to stderr. With `Markdown/Syntax` disabled, they are not reported; enabling it can make previously non-blocking parser warnings fail lint. `Markdown.WarnInvalid` continues to control invalid Ruby snippets independently.
+
+For Markdown style and prose checks, use [rubocop-prose](https://github.com/dblock/rubocop-prose).
 
-You can use this tricks
+### Disabling cops
+
+Use normal `# rubocop:disable`, `# rubocop:todo`, and `# rubocop:enable` directives inside Ruby code blocks. To disable cops across code blocks without displaying the directives in the rendered document, wrap them in hidden spans:
 
 ````md
 # my_post.md
@@ -136,20 +166,31 @@ end of snippet
 ... continuation of article ...
 ````
 
+HTML comments work too, and you can name individual cops instead of `all`:
+
+```md
+<!-- # rubocop:disable Style/EmptyMethod, Style/ArrayJoin -->
+
+Your Ruby code blocks here.
+
+<!-- # rubocop:enable Style/EmptyMethod, Style/ArrayJoin -->
+```
+
+Autocorrection preserves the HTML wrappers and does not apply corrections for disabled cops.
+
 ## How it works?
 
-- Preprocess Markdown source into Ruby source preserving line numbers
+- Parse Markdown once to identify code blocks and retain their source coordinates
+- Preprocess Ruby snippets while preserving line numbers and recording container prefixes
 - Let RuboCop do its job
-- Restore Markdown from preprocessed Ruby if it has been autocorrected
+- Map Ruby corrections back to the original Markdown, preserving indentation and list/blockquote prefixes
 
 ## Limitations
 
 - RuboCop cache is disabled for Markdown files (because cache knows nothing about preprocessing)
-- Uses naive Regexp-based approach to extract code blocks from Markdown, support only backticks-style code blocks\*
+- Code-block recognition follows Kramdown's GFM parser
 - No language detection included; if you do not specify language for your code blocks, you'd better turn `WarnInvalid` off (see above)
 
-\* It should be easy to integrate a _real_ parser (e.g. [Kramdown](https://kramdown.gettalong.org)) and handle all possible syntax. Feel free to open an issue or pull request!
-
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.

data/config/default.yml

@@ -7,6 +7,12 @@ Markdown:
   WarnInvalid: true
   Autodetect: true
 
+Markdown/Syntax:
+  Description: "Report Markdown parser warnings as offenses."
+  Enabled: false
+  Severity: warning
+  VersionAdded: "2.1"
+
 # Keep in sync with MARKDOWN_EXTENSIONS
 Layout/CommentIndentation: &markdown_excludes
   Exclude:
@@ -80,5 +86,5 @@ Style/FrozenStringLiteralComment:
   <<: *markdown_excludes
 
 Layout/LineLength:
-  IgnoredPatterns:
+  AllowedPatterns:
     - !ruby/regexp /^\#/

data/lib/rubocop/cop/markdown/syntax.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Markdown
+      # Reports Markdown parser diagnostics through RuboCop's standard formatters.
+      class Syntax < RuboCop::Cop::Base
+        def on_new_investigation
+          super
+          document = processed_source.markdown_document
+          return unless document
+
+          warnings_by_line = document.warnings.group_by do |warning|
+            warning_line(warning, document)
+          end
+          warnings_by_line.each do |number, warnings|
+            range = document.range(number, 0, number, document.line(number).length)
+            add_offense(document.processed_range(range), message: warnings.join("; "))
+          end
+        end
+
+        def on_other_file
+          super
+          on_new_investigation
+        end
+
+        private
+
+        def warning_line(warning, document)
+          number = warning.scan(/\bline (\d+)\b/).last&.first&.to_i
+          number&.between?(1, document.buffer.last_line) ? number : 1
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/markdown/document.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module RuboCop
+  module Markdown
+    # Original Markdown, its parsed blocks, and coordinates in the Ruby source buffer.
+    class Document
+      # A deliberate prose edit mapped into the shared Ruby correction buffer.
+      class ProseRange < ::Parser::Source::Range; end
+
+      attr_reader :buffer, :code_prefixes
+      attr_accessor :processed_buffer
+
+      def initialize(source, path)
+        @buffer = ::Parser::Source::Buffer.new(path, source: source)
+        @code_prefixes = {}
+      end
+
+      def code_blocks
+        return enum_for(__method__) unless block_given?
+
+        walk(root) { |node| yield node if node.type == :codeblock }
+      end
+
+      def code_lines(block)
+        first = block.options.fetch(:code_start_line)
+        block.options.fetch(:code_lines).each_with_index.to_h do |text, index|
+          number = first + index
+          original = line(number)
+          unless original.end_with?(text)
+            raise "Cannot map Markdown code block source on line #{number}"
+          end
+
+          code_prefixes[number] = original.delete_suffix(text)
+          [number, text]
+        end
+      end
+
+      def corrected_source(corrector)
+        rewriter = ::Parser::Source::TreeRewriter.new(buffer)
+        corrector.as_replacements.each do |range, replacement|
+          text = replacement.dup
+          Preprocess.restore!(text)
+          prefix = code_prefixes[range.first_line]
+          text = text.gsub("\n", "\n#{prefix}") if prefix
+          rewriter.replace(original_range(range), text)
+        end
+        rewriter.process
+      end
+
+      def warnings
+        parsed.last
+      end
+
+      def line(number)
+        buffer.source_line(number)
+      end
+
+      def original_range(processed)
+        return processed if processed.source_buffer.equal?(buffer)
+
+        range(
+          processed.first_line, [processed.column - line_offset(processed.first_line), 0].max,
+          processed.last_line, [processed.last_column - line_offset(processed.last_line), 0].max
+        )
+      end
+
+      def processed_range(original)
+        return original if original.source_buffer.equal?(processed_buffer)
+
+        ProseRange.new(
+          processed_buffer,
+          processed_position(original.first_line, original.column),
+          processed_position(original.last_line, original.last_column)
+        )
+      end
+
+      def range(first_line, first_column, last_line, last_column)
+        ::Parser::Source::Range.new(
+          buffer,
+          buffer.line_range(first_line).begin_pos + first_column,
+          buffer.line_range(last_line).begin_pos + last_column
+        )
+      end
+
+      private
+
+      def root
+        parsed.first
+      end
+
+      def parsed
+        @parsed ||= Markdown::Parser.parse(buffer.source, hard_wrap: false)
+      end
+
+      def walk(node, &block)
+        yield node
+        node.children.each { |child| walk(child, &block) }
+      end
+
+      def line_offset(number)
+        processed_buffer.source_line(number).length - line(number).length
+      end
+
+      def processed_position(number, column)
+        processed_buffer.line_range(number).begin_pos + line_offset(number) + column
+      end
+    end
+  end
+end

data/lib/rubocop/markdown/parser.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "kramdown-parser-gfm"
+
+module RuboCop
+  module Markdown
+    # Retains code-block source coordinates before Kramdown normalizes their content.
+    class Parser < Kramdown::Parser::GFM
+      # Accept metadata after the language without replacing Kramdown's block parser.
+      FENCED_CODEBLOCK_MATCH = /
+        ^[ ]{0,3}(([~`])\2{2,})[ \t]*((\S+)[^\n]*?)?[ \t]*\n
+        (.*?)^[ ]{0,3}\1\2*[ \t]*\n
+      /mx.freeze
+
+      def self.parse(source, options = {})
+        source = source.sub(
+          /\A(?:\uFEFF)?---[ \t]*\r?\n.*?^(?:---|\.\.\.)[ \t]*(?:\r?\n|\z)/m
+        ) { |header| header.gsub(/[^\r\n]/, " ") }
+        super
+      end
+
+      protected
+
+      def parse_codeblock_fenced
+        first = @src.pos
+        result = super
+        return result unless result
+
+        block = @tree.children.last
+        indent = @src.string.byteslice(first..)[/\A */].length
+        block.options[:code_start_line] = block.options[:location] + 1
+        block.options[:code_lines] = block.value.lines(chomp: true).map do |line|
+          line.sub(/\A {0,#{indent}}/, "")
+        end
+        result
+      end
+
+      def parse_codeblock
+        first = @src.pos
+        result = super
+        block = @tree.children.last
+        raw = @src.string.byteslice(first, @src.pos - first)
+        block.options[:code_start_line] = block.options[:location]
+        block.options[:code_lines] = raw.lines(chomp: true).map do |line|
+          line.sub(Kramdown::Parser::Kramdown::INDENT, "")
+        end
+        result
+      end
+    end
+  end
+end

data/lib/rubocop/markdown/preprocess.rb

@@ -7,19 +7,6 @@ module RuboCop
     # Transform source Markdown file into valid Ruby file
     # by commenting out all non-code lines
     class Preprocess
-      # This is a regexp to parse code blocks from .md files.
-      #
-      # Only recognizes backticks-style code blocks.
-      #
-      # Try it: https://rubular.com/r/YMqSWiBuh2TKIJ
-      MD_REGEXP = /
-        ^([[:blank:]]*`{3,4}) # Match opening backticks
-        ([\w[[:blank:]]+]*)?\n # Match the code block syntax
-        ([\s\S]+?) # Match everything inside the code block
-        (^[[:blank:]]*\1[[:blank:]]*\n?) # Match closing backticks
-        |(^.*$) # If we are not in a codeblock, match the whole line
-      /x.freeze
-
       MARKER = "<--rubocop/md-->"
 
       # See https://github.com/github/linguist/blob/v5.3.3/lib/linguist/languages.yml#L3925
@@ -33,18 +20,7 @@ module RuboCop
       ].freeze
 
       class << self
-        # Revert preprocess changes.
-        #
-        # When autocorrect is applied, RuboCop re-writes the file
-        # using preproccessed source buffer.
-        #
-        # We have to restore it.
-        def restore_and_save!(file)
-          contents = File.read(file)
-          restore!(contents)
-          File.write(file, contents)
-        end
-
+        # Remove preprocessing markers from correction text.
         def restore!(src)
           src.gsub!(/^#\s*#{MARKER}/m, "")
         end
@@ -53,32 +29,23 @@ module RuboCop
       attr_reader :config
 
       def initialize(file)
+        @file = file
         @config = Markdown.config_store.for(file)
       end
 
-      # rubocop:disable Metrics/MethodLength
-      def call(src)
-        src.gsub(MD_REGEXP) do |full_match|
-          m = Regexp.last_match
-          open_backticks = m[1]
-          syntax = m[2]
-          code = m[3]
-          close_backticks = m[4]
-          markdown = m[5]
-
-          if markdown
-            # We got markdown outside of a codeblock
-            comment_lines(markdown)
-          elsif ruby_codeblock?(syntax, code)
-            # The codeblock we parsed is assumed ruby, keep as is and append markers to backticks
-            "#{comment_lines(open_backticks + syntax)}\n#{code}#{comment_lines(close_backticks)}"
-          else
-            # The codeblock is not relevant, comment it out
-            comment_lines(full_match)
-          end
+      def call(src, document: Document.new(src, @file))
+        code = {}
+        document.code_blocks.each do |block|
+          syntax = block.options[:lang].to_s
+          lines = block.options.fetch(:code_lines)
+          next unless ruby_codeblock?(syntax, "#{lines.join("\n")}\n")
+
+          code.merge!(document.code_lines(block))
         end
+        src.lines.each_with_index.map do |line, index|
+          code.key?(index + 1) ? code.fetch(index + 1) + line[/\r?\n\z/].to_s : comment_lines(line)
+        end.join
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 

data/lib/rubocop/markdown/rubocop_ext.rb

@@ -27,6 +27,13 @@ module RuboCop
       def markdown_file?(file)
         MARKDOWN_EXTENSIONS.include?(File.extname(file))
       end
+
+      def ignored_offense?(cop_name, location)
+        return false if MARKDOWN_OFFENSE_COPS.include?(cop_name)
+        return false if location.is_a?(Document::ProseRange)
+
+        location.source_line.start_with?("##{Preprocess::MARKER}")
+      end
     end
   end
 end
@@ -41,7 +48,6 @@ RuboCop::Runner.prepend(Module.new do
 
   # Only cache markdown files if they have no offenses, 'cause cache doesn't know about processing.
   # NOTE: we should involve preprocessing in RuboCop::CachedData#deserialize_offenses
-  # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
   def file_offense_cache(file, ...)
     if cached_run? && RuboCop::Markdown.markdown_file?(file)
       config = @config_store.for_file(file)
@@ -65,16 +71,42 @@ RuboCop::Runner.prepend(Module.new do
       super
     end
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
+end)
 
-  def file_finished(file, offenses, ...)
-    return super unless RuboCop::Markdown.markdown_file?(file)
+RuboCop::Cop::Base.prepend(Module.new do
+  def add_offense(node_or_range, **options, &block)
+    location = range_from_node_or_range(node_or_range)
+    return if RuboCop::Markdown.ignored_offense?(cop_name, location)
 
-    # Run Preprocess.restore if file has been autocorrected
-    if @options[:auto_correct] || @options[:autocorrect]
-      RuboCop::Markdown::Preprocess.restore_and_save!(file)
-    end
+    super
+  end
+
+  private
+
+  def range_for_original(range)
+    document = processed_source.markdown_document
+    document ? document.original_range(range) : super
+  end
+end)
+
+RuboCop::Cop::Corrector.prepend(Module.new do
+  def initialize(source)
+    processed = source.respond_to?(:processed_source) ? source.processed_source : source
+    @markdown_document = processed.markdown_document if processed.respond_to?(:markdown_document)
+    super(@markdown_document ? @markdown_document.processed_buffer : source)
+  end
+
+  def rewrite
+    @markdown_document ? @markdown_document.corrected_source(self) : super
+  end
 
+  private
+
+  def to_range(node_or_range)
+    if @markdown_document && node_or_range.is_a?(Parser::Source::Range) &&
+       node_or_range.source_buffer.equal?(@markdown_document.buffer)
+      node_or_range = @markdown_document.processed_range(node_or_range)
+    end
     super
   end
 end)
@@ -82,13 +114,8 @@ end)
 RuboCop::Cop::Commissioner::InvestigationReport.prepend(Module.new do
   # Skip offenses reported for ignored MD source (trailing whitespaces, etc.)
   def offenses
-    @offenses ||= begin
-      marker_comment = "##{RuboCop::Markdown::Preprocess::MARKER}"
-      offenses_per_cop.flatten(1).reject do |offense|
-        next if RuboCop::Markdown::MARKDOWN_OFFENSE_COPS.include?(offense.cop_name)
-
-        offense.location.source_line.start_with?(marker_comment)
-      end
+    @offenses ||= offenses_per_cop.flatten(1).reject do |offense|
+      RuboCop::Markdown.ignored_offense?(offense.cop_name, offense.location)
     end
   end
 end)
@@ -102,10 +129,40 @@ end)
 
 # Extend ProcessedSource#parse with pre-processing
 RuboCop::ProcessedSource.prepend(Module.new do
+  attr_reader :markdown_document
+
+  def comments
+    return super unless path && RuboCop::Markdown.markdown_file?(path)
+
+    @markdown_comments ||= super.map { |comment| markdown_directive(comment) || comment }
+  end
+
   def parse(src, ...)
     # only process Markdown files
-    src = RuboCop::Markdown::Preprocess.new(path).call(src) if
-      path && RuboCop::Markdown.markdown_file?(path)
+    if path && RuboCop::Markdown.markdown_file?(path)
+      @markdown_comments = nil
+      @markdown_document = RuboCop::Markdown::Document.new(src, path)
+      src = RuboCop::Markdown::Preprocess.new(path).call(src, document: @markdown_document)
+    end
     super
+    @markdown_document.processed_buffer = @buffer if @markdown_document
+  end
+
+  private
+
+  def markdown_directive(comment)
+    return unless comment.text.start_with?("##{RuboCop::Markdown::Preprocess::MARKER}")
+
+    match = comment.text.match(
+      /(?:<!--|<span\b[^>]*>)\s*(#\s*rubocop:[^\n]*?)\s*(?:-->|<\/span>)\s*\z/
+    )
+    return unless match
+
+    location = comment.source_range
+    range = Parser::Source::Range.new(
+      location.source_buffer,
+      location.begin_pos + match.begin(1), location.begin_pos + match.end(1)
+    )
+    Parser::Source::Comment.new(range)
   end
 end)

data/lib/rubocop/markdown/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Markdown
-    VERSION = "2.0.4"
+    VERSION = "3.0.0"
   end
 end

data/lib/rubocop/markdown.rb

@@ -12,5 +12,7 @@ module RuboCop
     require_relative "markdown/preprocess"
     require_relative "markdown/rubocop_ext" if defined?(::RuboCop::ProcessedSource)
     require_relative "markdown/plugin"
+    require_relative "markdown/document"
+    require_relative "cop/markdown/syntax"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-md
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 3.0.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lint_roller
@@ -38,6 +38,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.72.1
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: kramdown-parser-gfm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -93,7 +121,10 @@ files:
 - README.md
 - config/default.yml
 - lib/rubocop-md.rb
+- lib/rubocop/cop/markdown/syntax.rb
 - lib/rubocop/markdown.rb
+- lib/rubocop/markdown/document.rb
+- lib/rubocop/markdown/parser.rb
 - lib/rubocop/markdown/plugin.rb
 - lib/rubocop/markdown/preprocess.rb
 - lib/rubocop/markdown/rubocop_ext.rb