rdoc-markdown 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5103b919452fc2a8143563d54ce1c2e7ab3e4aaf2afdfe44d6057fcce9a2e5c4
-  data.tar.gz: d8abe423253297371c5cb60c722bb24507c40d2a73ee9df37eca75a1b2dab60a
+  metadata.gz: 6f862496849b46537b75b6d25d1e313a830a9aaf535854a5233fad42081b0a0c
+  data.tar.gz: e7505ea0dadde9f2f6d357d96ce022e9b9cdc3b0a5457a1648a49bffb4c09fd4
 SHA512:
-  metadata.gz: 3fa2a3b9e6cc98af9902d054f3ad4989e05639f9f55da4bd2d5e4f5a984d9e97833d1c4d06898439a00907ad783ec7329ad46c2c8ae614fcc46a001ceea444fd
-  data.tar.gz: dedabad24735933e97d59127de66271a2a628287822e626c6eb4c5bf9631c613c512a05a511918c4a84fed34bffa61dd29166716fe61ae4badf38fa3e9220deb
+  metadata.gz: d6fb9ba4435a1b7e3ae3d9da59b2102a47574dc8c33570ca807358bec137116b17474a1721277d3ebe5833e1093b016fcc08a1dfd24d93f71f12b785382259ca
+  data.tar.gz: 3f25a645ec86e266b05fc0b934e2aa82f088011a6bf9906b881c796eff4c86684fafe05da70259fbdeb0c0221a2bfaf28262a867a292d58add5f1b4ca329bf5a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.22.0
+
+- BREAKING: Use Ruby notation in search-index names: `Duck.MAX_VELOCITY` becomes `Duck::MAX_VELOCITY`, and instance attributes use `Class#attr` instead of `Class.attr`. Consumers matching index names must update these lookups. Class-level attributes retain `Class.attr`; document paths and anchors are unchanged.
+- Replace `reverse_markdown` and its converter fork with RDoc's native `RDoc::Markup::ToMarkdown` formatter.
+
+## 0.21.2
+
+- Distinguish instance methods (`Class#method`) from class methods (`Class.method`) in search-index names, without changing their document paths or anchors.
+
 ## 0.21.1
 
 - Preserve hash-prefixed comments and literal Markdown headings in code examples when offsetting documentation headings.

data/README.md

@@ -1,15 +1,8 @@
 # RDoc-Markdown
 RDoc plugin to generate markdown documentation and search index file (CSV).
 
-> [!CAUTION]
-> This gem relies on multiple hacks to generate "plausible" markdown documentation. This is **NOT PRODUCTION READY** — use at your own risk.
->
-> RDoc maintainers are actively working on markdown support, things will improve with time...
-
 ## Motivation
-Markdown has become the de facto documentation standard. We can render markdown files on any device, possibly on a thermometer with a screen. And everyone knows markdown...
-
-It's a pity that RDoc can't output a proper markdown file. Somebody has to try to build it.
+Markdown has become the de facto documentation standard. Rdoc should be able to output it too.
 
 ## Installation
 
@@ -23,6 +16,12 @@ If Bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install rdoc-markdown
 
+Comments render directly through RDoc's native Markdown visitor. No
+`reverse_markdown` dependency or converter-fork override is required.
+Commonmarker (`~> 2.8`) is a runtime dependency used for Markdown AST parsing
+and serialization, not HTML rendering. Definition-list HTML is emitted directly;
+native documents never take an HTML-to-Markdown conversion round trip.
+
 
 ## Usage
 RDoc will auto-detect the rdoc-markdown plugin if it is installed. You just need to instruct RDoc to produce markdown output instead of standard HTML through the `format` parameter.
@@ -39,7 +38,7 @@ gem build rdoc-markdown.gemspec
 ```
 
 ```
-gem install <path-to>/rdoc-markdown-0.1.2.gem
+gem install <path-to>/rdoc-markdown-<version>.gem
 ```
 
 or you can do the same through a Gemfile:
@@ -66,12 +65,6 @@ sections: an anchor appearing only in a code example or a raw HTML block is not
 enough. This catches method headings swallowed by an unterminated Markdown HTML
 block, including aliases that link back to those methods.
 
-To lint markdown ERB templates:
-
-```
-bundle exec rake erb:lint
-```
-
 ### Generate vendored docs
 Use rake tasks to generate markdown output for vendored projects:
 
@@ -93,7 +86,7 @@ Find examples in the [/example](/example/) folder.
 
 ```
 gem build rdoc-markdown.gemspec
-gem push rdoc-markdown-0.1.2.gem
+gem push rdoc-markdown-<version>.gem
 ```
 
 There is a `./bin/publish.sh` script that does that. However, it assumes that you have the [gum library](https://github.com/charmbracelet/gum) installed.

data/lib/rdoc/discover.rb

@@ -1 +1,3 @@
-require "markdown"
+# frozen_string_literal: true
+
+require "rdoc/generator/markdown"

data/lib/rdoc/generator/markdown/blocks.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Native block visitors; nested fragments share context, not output buffers.
+  module Blocks
+    # Standalone source annotations, not documentation or inline examples.
+    LINTER_DIRECTIVE = /^(?:rubocop|standard):(?:disable|enable|todo)(?:[ \t]+[^\r\n]*)?(?:\r?\n|\z)/
+
+    # Visits nested documents and lists without resetting document state.
+    #
+    # @param document [RDoc::Markup::Document] Parsed comment document.
+    # @return [void]
+    def accept_document(document)
+      document.each do |part|
+        case part
+        when RDoc::Markup::Document
+          accept_document(part)
+        when RDoc::Markup::List
+          accept_list(part)
+        else
+          part.accept(self)
+        end
+      end
+    end
+
+    # Renders list contents natively, including code inside definition lists.
+    #
+    # @param list [RDoc::Markup::List] Parsed list.
+    # @return [void]
+    def accept_list(list)
+      type = list.type
+      unless [:BULLET, :NUMBER, :LALPHA, :UALPHA, :LABEL, :NOTE].include?(type)
+        raise RDoc::Error, "Invalid list type: #{type.inspect}"
+      end
+
+      definition = [:LABEL, :NOTE].include?(type)
+      entries = list.items
+      return html_list(type, entries) if definition_body && !definition
+
+      items = entries.each_with_index.map { |item, index| list_item(type, item, index) }.join("\n\n")
+      if definition
+        res << %(<dl class="rdoc-list #{type.downcase}-list">\n\n#{items}</dl>\n\n)
+      else
+        res << items << "\n\n"
+      end
+    end
+
+    # Quotes every line, preserving nested blocks and literal code.
+    #
+    # @param quote [RDoc::Markup::BlockQuote] Quoted markup nodes.
+    # @return [void]
+    def accept_block_quote(quote)
+      res << render_parts(quote.parts).lines.map { |line| "> #{line}" } << "\n\n"
+    end
+
+    # Preserves RDoc's namespaced and legacy heading anchors.
+    #
+    # @param heading [RDoc::Markup::Heading] Comment heading.
+    # @return [void]
+    def accept_heading(heading)
+      text = attributes(heading.text)
+      aliases = heading_aliases(heading, text)
+      if leading_native_link?(heading, text)
+        text = text.sub(/\A\[([^\]]+)\]\((#[^)]+)\)/) do
+          target = Regexp.last_match(2).delete_prefix("#")
+          aliases << target unless target == heading.aref
+          Regexp.last_match(1)
+        end
+      end
+      res << Syntax.heading(heading.level + rendering.heading_offset, text, aliases.uniq) << "\n\n"
+    end
+
+    # Converts embedded HTML using the existing compatibility rules.
+    #
+    # @param raw [RDoc::Markup::Raw] Raw HTML block.
+    # @return [void]
+    def accept_raw(raw)
+      res << HtmlInput.new(heading_level_offset: rendering.heading_offset).render(raw.parts.join("\n")) << "\n\n"
+    end
+
+    # Emits code without HTML escaping or syntax-highlighting round trips.
+    #
+    # @param verbatim [RDoc::Markup::Verbatim] Literal code block.
+    # @return [void]
+    def accept_verbatim(verbatim)
+      text = verbatim.text
+      language = verbatim.format
+      example = definition_list_example(text) unless language || definition_body
+      return res << example << "\n\n" if example
+      ruby_code = verbatim.ruby? || (!language && Prism.parse_success?(text))
+      language = "ruby" if ruby_code
+      if definition_body
+        klass = %( class="brush: #{CGI.escapeHTML(language.to_s)};") if language
+        content = CGI.escapeHTML(text.rstrip)
+        content << "\n" if ruby_code
+        res << "<pre#{klass}>#{content}</pre>\n\n"
+      else
+        res << Syntax.code_block(text, language) << "\n\n"
+      end
+    end
+
+    # Separates native tables from the paragraph that follows them.
+    #
+    # @param header [Array<String>] Column headings.
+    # @param body [Array<Array<String>>] Table rows.
+    # @param aligns [Array<Symbol, nil>] Column alignment hints.
+    # @return [void]
+    def accept_table(header, body, aligns)
+      rows = [header, *body].map { |row| table_row(row) }
+      rows.insert(1, aligns.map { "---" })
+      res << rows.map { |row| "| #{row.join(" | ")} |\n" } << "\n"
+    end
+
+    # Preserves RDoc's language-aware soft breaks and explicit hard breaks.
+    # @param paragraph [RDoc::Markup::Paragraph] Parsed paragraph.
+    # @return [void]
+    def accept_paragraph(paragraph)
+      text = paragraph_text(paragraph)
+      text = text.gsub(/(#{RDoc::Text::SPACE_SEPARATED_LETTER_CLASS})?\K(?:\r?\n)+(?=(?(1)(#{RDoc::Text::SPACE_SEPARATED_LETTER_CLASS})?))/o) { defined?($2) && " " }
+      # Main exposes Markdown-style headings in paragraphs, but never in verbatim.
+      definition = definition_body
+      heading = text.match(/\A {0,3}(\#{1,6})(?:[[:blank:]]+|\z)(.*)\z/) unless definition
+      markdown = if heading
+        Syntax.heading(heading[1].length, attributes(heading[2]), [])
+      else
+        attributes(text)
+      end
+      markdown = "<p>#{InlineHtml.render(markdown)}</p>" if definition
+      wrap(markdown)
+    end
+
+    # Emits paragraphs without wrapping Markdown links across lines.
+    #
+    # @param text [String] Inline Markdown.
+    # @return [void]
+    def wrap(text)
+      res << text << "\n\n"
+    end
+
+    private
+
+    # Removes source annotations without changing their occurrences inside code.
+    # @param paragraph [RDoc::Markup::Paragraph] Original parsed paragraph.
+    # @return [String] Prose with code and hard breaks preserved.
+    def paragraph_text(paragraph)
+      text_parts = paragraph.parts.map { |part| RDoc::Markup::Paragraph.new(part).text("<br>\n").encode(Encoding::UTF_8) }
+      ranges = Syntax.code_ranges(text_parts.join)
+      prefix = +""
+      text = text_parts.map do |part|
+        offset = prefix.bytesize
+        prefix << part
+        strip_linter_directives(part, offset, ranges)
+      end.join
+      text.force_encoding(paragraph.text.encoding) if text.ascii_only?
+      text
+    end
+
+    # Strips only annotation matches outside literal inline source.
+    # @param text [String] UTF-8 paragraph part.
+    # @param offset [Integer] Original part's source byte offset.
+    # @param ranges [Array<Range<Integer>>] Literal source ranges.
+    # @return [String] Filtered paragraph part.
+    def strip_linter_directives(text, offset, ranges)
+      text.gsub(LINTER_DIRECTIVE) do |line|
+        position = offset + Regexp.last_match.pre_match.bytesize
+        line if Syntax.literal_position?(ranges, position)
+      end
+    end
+
+    # Restores main's Markdown lists for complete indented term-and-bullet examples.
+    # @param text [String] Unclassified verbatim content.
+    # @return [String, nil] Markdown list, or nil when any line is ordinary code.
+    def definition_list_example(text)
+      lines = text.lines.map(&:strip)
+      valid_lines = lines.all? { |line| line.empty? || line.end_with?("::") || line.match?(/\A\*\s/) }
+      return unless lines.first&.end_with?("::") && valid_lines && lines.grep(/\A\*\s/).any?
+
+      lines.map { |line| line.sub(/::\z/, ":").sub(/\A\*\s/, "- ") }.join("\n")
+    end
+
+    # Nested lists stay in the final HTML definition container, like main.
+    # @param type [Symbol] Validated ordinary list type.
+    # @param entries [Array<RDoc::Markup::ListItem>] Native list items.
+    # @return [void]
+    def html_list(type, entries)
+      opening, closing = RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML.fetch(type)
+      res << opening
+      entries.each { |item| res << "<li>\n\n#{render_parts(item.parts)}\n\n</li>\n\n" }
+      res << closing << "\n\n"
+    end
+
+    # Indents continuation blocks by the width of their actual list marker.
+    #
+    # @param type [Symbol] RDoc list type.
+    # @param item [RDoc::Markup::ListItem] Item containing native markup nodes.
+    # @param index [Integer] Zero-based item index.
+    # @return [String] Markdown list item or HTML definition container.
+    def list_item(type, item, index)
+      definition = [:LABEL, :NOTE].include?(type)
+      body = render_parts(item.parts, definition: definition)
+      return definition_item(item.label, body) if definition
+
+      marker = (type == :BULLET) ? "-" : "#{index + 1}."
+      "#{marker} #{body.gsub("\n", "\n#{" " * (marker.length + 1)}")}"
+    end
+
+    # Blank lines allow GFM to parse native Markdown inside definition containers.
+    #
+    # @param label [String, Array<String>, nil] Definition terms.
+    # @param body [String] Native Markdown for the description.
+    # @return [String] Definition item with Markdown-enabled HTML boundaries.
+    def definition_item(label, body)
+      terms = Array(label).map { |term| "<dt>#{InlineHtml.render(attributes(term))}</dt>\n" }.join
+      "#{terms}<dd>\n\n#{body}\n\n</dd>\n\n"
+    end
+
+    # Renders nested blocks without resetting shared heading IDs or cross-references.
+    #
+    # @param parts [Array<Object>] Child markup nodes.
+    # @param definition [Boolean, nil] Final HTML definition-body boundary.
+    # @return [String] Nested Markdown.
+    def render_parts(parts, definition: definition_body)
+      visitor = dup
+      visitor.definition_body = definition
+      RDoc::Markup::Document.new(*parts).accept(visitor).rstrip
+    end
+
+    # Formats table cells in their own inline escaping context.
+    # @param cells [Array<String>] RDoc cell contents.
+    # @return [Array<String>] GFM-safe cells.
+    def table_row(cells)
+      cells.map { |cell| attributes(cell).gsub("|", '\\|') }
+    end
+
+    # Computes compatible heading aliases from RDoc's canonical label methods.
+    # @param heading [RDoc::Markup::Heading] Parsed heading.
+    # @param text [String] Native inline heading Markdown.
+    # @return [Array<String>] Legacy and namespaced IDs.
+    def heading_aliases(heading, text)
+      object = rendering.object
+      modern = unique_heading_id(heading.label(object))
+      legacy = unique_heading_id(heading.legacy_label(object))
+      aliases = []
+      aliases << legacy unless RDoc::ClassModule === object && heading.level == 1
+      canonical = RDoc::Text.to_anchor(Syntax.node_text(Commonmarker.parse(text.encode(Encoding::UTF_8))))
+      aliases << modern unless text.empty? || modern == canonical || leading_native_link?(heading, text)
+      aliases
+    end
+
+    # Main drops the outer self-link before native links, but sees Markdown as text.
+    # @param heading [RDoc::Markup::Heading] Original heading source.
+    # @param text [String] Native inline heading Markdown.
+    # @return [Boolean] Whether the first inline node is a native link.
+    def leading_native_link?(heading, text)
+      text.start_with?("[") && !heading.text.start_with?("[")
+    end
+
+    # Deduplicates IDs across the document and its native child visitors.
+    # @param id [String] RDoc heading ID.
+    # @return [String] Unique heading ID.
+    def unique_heading_id(id)
+      ids = rendering.heading_ids
+      count = ids[id]
+      ids[id] = count + 1
+      count.zero? ? id : "#{id}-#{count}"
+    end
+  end
+end

data/lib/rdoc/generator/markdown/descriptions.rb

@@ -33,42 +33,25 @@ module RDoc::Generator::Markdown::Descriptions
   # Renders an RDoc description with links limited to emitted objects.
   #
   # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Object whose description is rendered.
+  # @param heading_level_offset [Integer] Levels to add to comment headings.
   #
-  # @return [String] HTML description.
-  def render_description(code_object)
-    formatter = description_formatter(code_object)
-    formatter.extend(RDoc::Generator::Markdown::CrossrefExtension)
-    formatter.with_markdown_cross_references(
-      RDoc::CrossReference.new(formatter.context),
-      generation_state.markdown_output_object_ids
-    ) do
-      render_formatted_description(code_object, formatter, options.locale)
+  # @return [String] Markdown description.
+  def render_description(code_object, heading_level_offset:)
+    formatter = RDoc::Generator::Markdown::Formatter.new(
+      code_object,
+      output_object_ids: generation_state.markdown_output_object_ids,
+      heading_level_offset: heading_level_offset
+    )
+    locale = options.locale
+    document = if RDoc::Context::Section === code_object
+      documents = code_object.comments.map { |comment| localized_comment_document(comment, locale) }
+      RDoc::Markup::Document.new(*documents)
+    else
+      comment = (RDoc::ClassModule === code_object) ? code_object.comment_location : code_object.comment
+      comment = RDoc::I18n::Text.new(comment).translate(locale) if locale
+      code_object.parse(comment)
     end
-  end
-
-  # Returns the formatter appropriate for an object or section.
-  #
-  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Described object.
-  #
-  # @return [RDoc::Markup::Formatter] Formatter configured for the object.
-  def description_formatter(code_object)
-    return code_object.formatter unless RDoc::Context::Section === code_object
-
-    code_object.parent.formatter.dup.tap { |copy| copy.code_object = code_object }
-  end
-
-  # Renders an object through its configured formatter.
-  #
-  # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Described object.
-  # @param formatter [RDoc::Markup::Formatter] Formatter receiving parsed markup.
-  # @param locale [RDoc::I18n::Locale, nil] Translation locale.
-  #
-  # @return [String] Formatted HTML description.
-  def render_formatted_description(code_object, formatter, locale)
-    return code_object.description unless RDoc::Context::Section === code_object
-
-    documents = code_object.comments.map { |comment| localized_comment_document(comment, locale) }
-    RDoc::Markup::Document.new(*documents).accept(formatter)
+    document.accept(formatter).rstrip
   end
 
   # Parses one section comment, translating a copy when needed.
@@ -93,25 +76,10 @@ module RDoc::Generator::Markdown::Descriptions
   #
   # @return [String] Rendered description or fallback text.
   def describe(code_object, fallback: nil, heading_level_offset: 0)
-    description = render_description(code_object)
-    return fallback.to_s if description.empty?
-
     comment = code_object.comment
     heading_level_offset = 0 if RDoc::Comment === comment && comment.format == "markdown"
-    RDoc::Generator::Markdown::Conversion.markdownify(description, heading_level_offset: heading_level_offset)
-  end
-
-  # Renders a section description as Markdown.
-  #
-  # @param section [RDoc::Context::Section] RDoc section whose description appears before grouped members.
-  # @param heading_level_offset [Integer] Heading levels to add while rendering.
-  #
-  # @return [String] Rendered section description.
-  def section_description(section, heading_level_offset:)
-    RDoc::Generator::Markdown::Conversion.markdownify(
-      render_description(section),
-      heading_level_offset: heading_level_offset
-    )
+    description = render_description(code_object, heading_level_offset: heading_level_offset)
+    description.empty? ? fallback.to_s : description
   end
 
   # Renders a method description or an alias fallback.
@@ -128,20 +96,27 @@ module RDoc::Generator::Markdown::Descriptions
     aliased_method = method.is_alias_for
     return "Not documented." unless aliased_method
 
-    alias_description(aliased_method, method_link(aliased_method, current_class: current_class))
+    name = aliased_method.name
+    link = method_link(aliased_method, current_class: current_class)
+    link ? "Alias for: [`#{name}`](#{link})" : "Alias for: `#{name}`"
   end
 
-  # Formats an alias fallback with an optional target link.
+  # Lists aliases that have generated documentation sections.
   #
-  # @param aliased_method [RDoc::AnyMethod] Alias target.
-  # @param link [String, nil] Generated link target.
+  # @param method [RDoc::AnyMethod] Canonical method.
   #
-  # @return [String] Alias description.
-  def alias_description(aliased_method, link)
-    name = aliased_method.name
-    return "Alias for: `#{name}`" unless link
+  # @return [String, nil] Linked alias list, or nil when none are emitted.
+  def method_aliases(method)
+    links = method.aliases.filter_map do |aka|
+      # RDoc's module_function copies share alias arrays with their instance methods.
+      next unless aka.is_alias_for.equal?(method)
+
+      link = method_link(aka, current_class: method.parent)
+      "[`#{aka.name}`](#{link})" if link
+    end
+    return if links.empty?
 
-    "Alias for: [`#{name}`](#{link})"
+    "Also known as: #{links.join(", ")}"
   end
 
   # Builds a Markdown link target for an aliased method.
@@ -154,6 +129,7 @@ module RDoc::Generator::Markdown::Descriptions
     return unless method.display?
 
     target_parent = method.parent
+    return unless target_parent
     return unless target_parent.method_list.include?(method)
 
     target_path = generation_state.class_output_paths[target_parent.full_name]

data/lib/rdoc/generator/markdown/formatter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rdoc/markup/to_markdown"
+require "prism"
+require "commonmarker"
+require_relative "markdown_links"
+require_relative "inline_html"
+require_relative "inline"
+require_relative "blocks"
+
+class RDoc::Generator::Markdown
+  # One native visitor with separate block, inline, and reference responsibilities.
+  class Formatter < RDoc::Markup::ToMarkdown
+    include References
+    include Inline
+    include Blocks
+
+    # Context shared by child visitors; each child owns its native output buffer.
+    Rendering = Data.define(:object, :context, :reference, :output_ids, :heading_offset, :heading_ids)
+
+    # Immutable render configuration and document-scoped heading IDs.
+    # @return [Rendering] Current document context.
+    attr_reader :rendering
+
+    # Child visitors inherit the final HTML boundary of a definition-list body.
+    # @return [Boolean, nil] Whether blocks are inside a definition description.
+    attr_accessor :definition_body
+
+    # Block visitors emit their own paragraph spacing.
+    alias_method :accept_blank_line, :ignore
+
+    # Initializes the native formatter and its document-scoped references.
+    # @param code_object [RDoc::CodeObject, RDoc::Context::Section] Described object.
+    # @param output_object_ids [Set<Integer>] Emitted objects.
+    # @param heading_level_offset [Integer] Levels to add to comment headings.
+    def initialize(code_object, output_object_ids:, heading_level_offset:)
+      super()
+      context = (RDoc::Context === code_object) ? code_object : code_object.parent
+      @rendering = Rendering.new(code_object, context, RDoc::CrossReference.new(context), output_object_ids, heading_level_offset, Hash.new(0))
+      @from_path = context.path
+      configure_inline
+    end
+  end
+end

data/lib/rdoc/generator/markdown/html_input.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+class RDoc::Generator::Markdown
+  # Explicit HTML input boundary; never used to render native RDoc nodes.
+  class HtmlInput
+    # Native delimiters for the inline HTML tags accepted at this boundary.
+    INLINE_MARKERS = {"strong" => "**", "b" => "**", "em" => "*", "i" => "*", "del" => "~~", "s" => "~~"}.freeze
+
+    # Creates an adapter with the surrounding comment's heading offset.
+    # @param heading_level_offset [Integer] Levels to add to HTML headings.
+    def initialize(heading_level_offset:)
+      @heading_level_offset = heading_level_offset
+    end
+
+    # Preserves HTML-only constructs and adapts supported elements to native GFM.
+    # @param html [String] Explicit raw HTML input.
+    # @return [String] Markdown fragment.
+    def render(html)
+      fragment = Nokogiri::HTML.fragment(html)
+      fragment.css("span.legacy-anchor[id]").each { |span| position_anchor(span) }
+      nodes = fragment.children.reject { |node| node.text? && !node.text.match?(/\S/) }
+      render_nodes(nodes).strip
+    end
+
+    private
+
+    # Keeps legacy spans beside their heading without exposing context aliases.
+    # @param span [Nokogiri::XML::Element] Legacy anchor.
+    # @return [void]
+    def position_anchor(span)
+      heading = span.next_element
+      if heading&.name == "h1" && span["id"].match?(/\A(?:class|module)-/)
+        span.remove
+      elsif heading&.name&.match?(/\Ah[1-6]\z/)
+        heading.add_child(span)
+      end
+    end
+
+    # Formats adjacent input nodes without reparsing emitted Markdown.
+    # @param nodes [Nokogiri::XML::NodeSet] Input siblings.
+    # @return [String] Native Markdown.
+    def render_nodes(nodes)
+      nodes.map { |node| render_node(node) }.join
+    end
+
+    # Dispatches explicit HTML blocks and native inline primitives.
+    # @param node [Nokogiri::XML::Node] HTML input node.
+    # @return [String] Native Markdown or preserved raw HTML.
+    def render_node(node)
+      return Syntax.escape(node.content.tr("\n", " ")) if node.text?
+
+      case node.name
+      when "p" then paragraph(node)
+      when /\Ah[1-6]\z/ then heading(node)
+      when "pre" then preformatted(node)
+      when "code", "tt" then Syntax.code(node.text)
+      when "br" then "<br>"
+      when *INLINE_MARKERS.keys, "a", "span", "div" then inline_element(node)
+      else preserve_html(node)
+      end
+    end
+
+    # Separates paragraphs from preceding standalone anchor spans.
+    # @param node [Nokogiri::XML::Element] Paragraph element.
+    # @return [String] Paragraph Markdown.
+    def paragraph(node)
+      prefix = "\n\n" if node.previous_element&.name == "span"
+      "#{prefix}#{render_nodes(node.children)}\n\n"
+    end
+
+    # Keeps literal indentation while removing the conventional opening newline.
+    # @param node [Nokogiri::XML::Element] Preformatted HTML input.
+    # @return [String] Native fenced code.
+    def preformatted(node)
+      css = node["class"].to_s
+      language = css[/\A(?!highlight\z)[A-Za-z][A-Za-z0-9_+-]*\z/] ||
+        css[/\Abrush: (\w+);\z/, 1] || node.parent["class"].to_s[/\Ahighlight-(\w+)\z/, 1]
+      "#{Syntax.code_block(node.text.delete_prefix("\n"), language)}\n\n"
+    end
+
+    # Converts only known inline tags, preserving explicit anchor identities.
+    # @param node [Nokogiri::XML::Element] Inline or transparent container.
+    # @return [String] Inline Markdown.
+    def inline_element(node)
+      name = node.name
+      content = render_nodes(node.children)
+      marker = INLINE_MARKERS[name]
+      return "#{marker}#{content}#{marker}" if marker
+
+      id = node["id"]
+      link = name == "a"
+      return Syntax.anchor(id) if id && (link || node["class"] == "legacy-anchor")
+      return content unless link
+
+      href = node["href"]
+      href ? Syntax.link(content, href) : content
+    end
+
+    # Leaves unsupported HTML intact while mapping its actual link targets.
+    # @param node [Nokogiri::XML::Element] HTML-only construct.
+    # @return [String] Preserved HTML block.
+    def preserve_html(node)
+      node.css("a[href]").each { |link| link["href"] = Syntax.target(link["href"]) }
+      "#{node}\n\n"
+    end
+
+    # Flattens leading heading self-links and retains their noncanonical aliases.
+    # @param node [Nokogiri::XML::Element] Heading element.
+    # @return [String] Native Markdown heading.
+    def heading(node)
+      spans = node.css("span.legacy-anchor[id]")
+      aliases = spans.map { |span| span["id"] }
+      spans.remove
+      first = node.element_children.first
+      href = first&.[]("href").to_s
+      if first&.name == "a" && href.match?(/\A#./) &&
+          first.text.match?(/\S/) && first.xpath("preceding-sibling::node()").none? { |sibling| sibling.text.match?(/\S/) }
+        id = href.delete_prefix("#")
+        first.replace(first.children)
+        aliases << id unless id == RDoc::Text.to_anchor(node.text)
+      end
+      text = render_nodes(node.children).strip
+      "#{Syntax.heading(Integer(node.name.delete_prefix("h")) + @heading_level_offset, text, aliases)}\n\n"
+    end
+  end
+end