rdoc-markdown 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0eae6267dc89dd3b398c7498a2cc7d9458feb1b177a66dbd5dcdd20d1c421e4
-  data.tar.gz: 8dff34ad7b48a1bd9b0a06a8b395490427888427425dc24e4551eee48a75028d
+  metadata.gz: 405929506a512e2000ebf5446b834abc96b1d5547fc3d6ec09daecf28356f4d5
+  data.tar.gz: b3d82d2787e012d16d9ca72d72fa2617e096315ea11eb80db0874fd609cb938b
 SHA512:
-  metadata.gz: bee22d3e444a8bbc5bf4fc0d0e5f6f9c269b8dd5ae70c9e00a91b9b41dad23490b51b56bfe3af6d7dcbc20e0d0e73e2afd2bf1a224598da29610ba08f713eec5
-  data.tar.gz: 7836c11cd909c34211aac0a0e4908e7d25143bc9ccf4296a973f0ddadf4c1b205658ce1e6fffb76f48f227193ffb811cd41e4ad7ab273438ff54eda8263af0a8
+  metadata.gz: acf30a9851cbb932c3a51a05541b296cb0d2f5c5b910b40812824c43c69ee9e423312c3b07ccceff901b0cea2889bc5f2f8373bd0a79f40985d232183185d5e5
+  data.tar.gz: 6d994d364f33251761a52f58e69dc534cd4806c2eea806e9d536f65b681a92b4d0b1e096436012c3d0aad6dac07bcad379620ce7a94b09ebd2c28e43bf9349d6

data/.yard-lint.yml

@@ -13,7 +13,7 @@ AllValidators:
     - "spec/**/*"
     - "test/**/*"
     - "tmp/**/*"
-    - lib/rdoc/markdown/version.rb
+    - "lib/rdoc/markdown/version.rb"
 
   FailOnSeverity: error
   MinCoverage: 100.0

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.11.0
+
+### Changed
+- properly convert code block to markdown with language definition
+
+### Fixed
+- Put generated anchors before heading lines so terminal markdown renderers parse headings correctly.
+
 ## 0.10.3
 - Remove extra spacing between title 3 and content
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rdoc-markdown (0.10.3)
+    rdoc-markdown (0.11.0)
       csv
       erb
       rdoc

data/example/Bird.md

@@ -1,13 +1,11 @@
-# Class Bird
 <a id="class-bird"></a>
-
+# Class Bird
 The base class for all birds.
 
 ### Public Instance Methods
 
-#### `fly(direction: string, velocity: number) -> bool`
 <a id="method-i-fly"></a>
-
+#### `fly(direction: string, velocity: number) -> bool`
 Fly somewhere.
 
 Flying is the most critical feature of birds.
@@ -18,7 +16,6 @@ Flying is the most critical feature of birds.
 fly(:south, 70)
 ```
 
-#### `speak() { |text| ... }`
 <a id="method-i-speak"></a>
-
+#### `speak() { |text| ... }`
 Produce some noise.

data/example/Duck.md

@@ -1,6 +1,5 @@
-# Class Duck
 <a id="class-duck"></a>
-
+# Class Duck
 A duck is a [`Waterfowl`](Waterfowl.md) [`Bird`](Bird.md).
 
 Features:
@@ -18,47 +17,40 @@ waterfowl:
 
 ### Public Instance Methods
 
-#### `speak() { |speech| ... }`
 <a id="method-i-speak"></a>
-
+#### `speak() { |speech| ... }`
 [`Duck`](Duck.md) overrides generic implementation.
 
 ## Duck extensions
 
 ### Constants
 
-#### `MAX_VELOCITY`
 <a id="MAX_VELOCITY"></a>
-
+#### `MAX_VELOCITY`
 Not documented.
 
 ### Attributes
 
-#### `domestic` [RW]
 <a id="attribute-i-domestic"></a>
-
+#### `domestic` [RW]
 True for domestic ducks.
 
-#### `rubber` [R]
 <a id="attribute-i-rubber"></a>
-
+#### `rubber` [R]
 True for rubber ducks.
 
 ### Public Class Methods
 
-#### `new(domestic, rubber)`
 <a id="method-c-new"></a>
-
+#### `new(domestic, rubber)`
 Creates a new duck.
 
-#### `rubber_ducks()`
 <a id="method-c-rubber_ducks"></a>
-
+#### `rubber_ducks()`
 Returns list of all rubber ducks.
 
 ### Public Instance Methods
 
-#### `useful? -> bool`
 <a id="method-i-useful-3F"></a>
-
+#### `useful? -> bool`
 Checks if this duck is a useful one.

data/example/Object.md

@@ -1,9 +1,8 @@
-# Class Object
 <a id="class-object"></a>
+# Class Object
 
 ### Constants
 
-#### `DEFAULT_DUCK_VELOCITY`
 <a id="DEFAULT_DUCK_VELOCITY"></a>
-
+#### `DEFAULT_DUCK_VELOCITY`
 Default velocity for a flying duck.

data/example/Waterfowl.md

@@ -1,11 +1,9 @@
-# Module Waterfowl
 <a id="module-waterfowl"></a>
-
+# Module Waterfowl
 A mixin for waterfowl creatures.
 
 ### Public Instance Methods
 
-#### `swim()`
 <a id="method-i-swim"></a>
-
+#### `swim()`
 Swimming helper.

data/example/jekyll-seo-tag/Jekyll/SeoTag/AuthorDrop.md

@@ -1,6 +1,5 @@
-# Class Jekyll::SeoTag::AuthorDrop
 <a id="class-jekyll-seotag-authordrop"></a>
-
+# Class Jekyll::SeoTag::AuthorDrop
 A drop representing the current page’s author
 
 Author name will be pulled from:
@@ -15,26 +14,22 @@ If the result from the name search is a string, we’ll also check for additiona
 
 ### Public Class Methods
 
-#### `new(page: nil, site: nil)`
 <a id="method-c-new"></a>
-
+#### `new(page: nil, site: nil)`
 Initialize a new [`AuthorDrop`](AuthorDrop.md)
 
 page - The page hash (e.g., Page#to\_liquid) site - The Jekyll::Drops::SiteDrop
 
 ### Public Instance Methods
 
-#### `name()`
 <a id="method-i-name"></a>
-
+#### `name()`
 [`AuthorDrop#to_s`](AuthorDrop.md#method-i-to_s) should return name, allowing the author drop to safely replace `page.author`, if necessary, and remain backwards compatible
 
-#### `to_s()`
 <a id="method-i-to_s"></a>
-
+#### `to_s()`
 Alias for: [`name`](#method-i-name)
 
-#### `twitter()`
 <a id="method-i-twitter"></a>
-
+#### `twitter()`
 Not documented.

data/example/jekyll-seo-tag/Jekyll/SeoTag/Drop.md

@@ -1,133 +1,108 @@
-# Class Jekyll::SeoTag::Drop
 <a id="class-jekyll-seotag-drop"></a>
+# Class Jekyll::SeoTag::Drop
 
 ### Constants
 
-#### `FORMAT_STRING_METHODS`
 <a id="FORMAT_STRING_METHODS"></a>
-
+#### `FORMAT_STRING_METHODS`
 Not documented.
 
-#### `HOMEPAGE_OR_ABOUT_REGEX`
 <a id="HOMEPAGE_OR_ABOUT_REGEX"></a>
-
+#### `HOMEPAGE_OR_ABOUT_REGEX`
 Not documented.
 
-#### `TITLE_SEPARATOR`
 <a id="TITLE_SEPARATOR"></a>
-
+#### `TITLE_SEPARATOR`
 Not documented.
 
 ### Public Class Methods
 
-#### `new(text, context)`
 <a id="method-c-new"></a>
-
+#### `new(text, context)`
 Not documented.
 
 ### Public Instance Methods
 
-#### `author()`
 <a id="method-i-author"></a>
-
+#### `author()`
 A drop representing the page author
 
-#### `canonical_url()`
 <a id="method-i-canonical_url"></a>
-
+#### `canonical_url()`
 Not documented.
 
-#### `date_modified()`
 <a id="method-i-date_modified"></a>
-
+#### `date_modified()`
 Not documented.
 
-#### `date_published()`
 <a id="method-i-date_published"></a>
-
+#### `date_published()`
 Not documented.
 
-#### `description()`
 <a id="method-i-description"></a>
-
+#### `description()`
 Not documented.
 
-#### `image()`
 <a id="method-i-image"></a>
-
+#### `image()`
 Returns a [`Drop`](Drop.md) representing the page’s image Returns nil if the image has no path, to preserve backwards compatability
 
-#### `json_ld()`
 <a id="method-i-json_ld"></a>
-
+#### `json_ld()`
 A drop representing the JSON-LD output
 
-#### `links()`
 <a id="method-i-links"></a>
-
+#### `links()`
 Not documented.
 
-#### `logo()`
 <a id="method-i-logo"></a>
-
+#### `logo()`
 Not documented.
 
-#### `name()`
 <a id="method-i-name"></a>
-
+#### `name()`
 rubocop:enable Metrics/CyclomaticComplexity
 
-#### `page_lang()`
 <a id="method-i-page_lang"></a>
-
+#### `page_lang()`
 Not documented.
 
-#### `page_locale()`
 <a id="method-i-page_locale"></a>
-
+#### `page_locale()`
 Not documented.
 
-#### `page_title()`
 <a id="method-i-page_title"></a>
-
+#### `page_title()`
 Page title without site title or description appended
 
-#### `site_description()`
 <a id="method-i-site_description"></a>
-
+#### `site_description()`
 Not documented.
 
-#### `site_tagline()`
 <a id="method-i-site_tagline"></a>
-
+#### `site_tagline()`
 Not documented.
 
-#### `site_tagline_or_description()`
 <a id="method-i-site_tagline_or_description"></a>
-
+#### `site_tagline_or_description()`
 Not documented.
 
-#### `site_title()`
 <a id="method-i-site_title"></a>
-
+#### `site_title()`
 Not documented.
 
-#### `title()`
 <a id="method-i-title"></a>
-
+#### `title()`
 Page title with site title or description appended rubocop:disable Metrics/CyclomaticComplexity
 
-#### `title?()`
 <a id="method-i-title-3F"></a>
-
+#### `title?()`
 Should the ‘\<title\>` tag be generated for this page?
 
-#### `type()`
 <a id="method-i-type"></a>
-
+#### `type()`
 Not documented.
 
-#### `version()`
 <a id="method-i-version"></a>
-
+#### `version()`
 Not documented.

data/example/jekyll-seo-tag/Jekyll/SeoTag/Filters.md

@@ -1,9 +1,8 @@
-# Class Jekyll::SeoTag::Filters
 <a id="class-jekyll-seotag-filters"></a>
+# Class Jekyll::SeoTag::Filters
 
 ### Public Class Methods
 
-#### `new(context)`
 <a id="method-c-new"></a>
-
+#### `new(context)`
 Not documented.

data/example/jekyll-seo-tag/Jekyll/SeoTag/ImageDrop.md

@@ -1,6 +1,5 @@
-# Class Jekyll::SeoTag::ImageDrop
 <a id="class-jekyll-seotag-imagedrop"></a>
-
+# Class Jekyll::SeoTag::ImageDrop
 A drop representing the page image The image path will be pulled from:
 
 1. The `image` key if it’s a string
@@ -13,21 +12,18 @@ A drop representing the page image The image path will be pulled from:
 
 ### Public Class Methods
 
-#### `new(page: nil, context: nil)`
 <a id="method-c-new"></a>
-
+#### `new(page: nil, context: nil)`
 Initialize a new [`ImageDrop`](ImageDrop.md)
 
 page - The page hash (e.g., Page#to\_liquid) context - the Liquid::Context
 
 ### Public Instance Methods
 
-#### `path()`
 <a id="method-i-path"></a>
-
+#### `path()`
 Called path for backwards compatability, this is really the escaped, absolute URL representing the page’s image Returns nil if no image path can be determined
 
-#### `to_s()`
 <a id="method-i-to_s"></a>
-
+#### `to_s()`
 Alias for: [`path`](#method-i-path)

data/example/jekyll-seo-tag/Jekyll/SeoTag/JSONLD.md

@@ -1,18 +1,15 @@
-# Module Jekyll::SeoTag::JSONLD
 <a id="module-jekyll-seotag-jsonld"></a>
-
+# Module Jekyll::SeoTag::JSONLD
 This module is deprecated, but is included in the Gem to avoid a breaking change and should be removed at the next major version bump
 
 ### Constants
 
-#### `METHODS_KEYS`
 <a id="METHODS_KEYS"></a>
-
+#### `METHODS_KEYS`
 Not documented.
 
 ### Public Instance Methods
 
-#### `json_ld()`
 <a id="method-i-json_ld"></a>
-
+#### `json_ld()`
 Self should be a [`Jekyll::SeoTag::Drop`](Drop.md) instance (when extending the module)

data/example/jekyll-seo-tag/Jekyll/SeoTag/JSONLDDrop.md

@@ -1,41 +1,34 @@
-# Class Jekyll::SeoTag::JSONLDDrop
 <a id="class-jekyll-seotag-jsonlddrop"></a>
+# Class Jekyll::SeoTag::JSONLDDrop
 
 ### Public Class Methods
 
-#### `new(page_drop)`
 <a id="method-c-new"></a>
-
+#### `new(page_drop)`
 page\_drop should be an instance of [`Jekyll::SeoTag::Drop`](Drop.md)
 
 ### Public Instance Methods
 
-#### `author()`
 <a id="method-i-author"></a>
-
+#### `author()`
 Not documented.
 
-#### `fallback_data()`
 <a id="method-i-fallback_data"></a>
-
+#### `fallback_data()`
 Not documented.
 
-#### `image()`
 <a id="method-i-image"></a>
-
+#### `image()`
 Not documented.
 
-#### `mainEntityOfPage()`
 <a id="method-i-mainEntityOfPage"></a>
-
+#### `mainEntityOfPage()`
 Alias for: [`main_entity`](#method-i-main_entity)
 
-#### `publisher()`
 <a id="method-i-publisher"></a>
-
+#### `publisher()`
 Not documented.
 
-#### `to_json(state = nil)`
 <a id="method-i-to_json"></a>
-
+#### `to_json(state = nil)`
 Returns a JSON-encoded object containing the JSON-LD data. Keys are sorted.

data/example/jekyll-seo-tag/Jekyll/SeoTag/UrlHelper.md

@@ -1,5 +1,4 @@
-# Module Jekyll::SeoTag::UrlHelper
 <a id="module-jekyll-seotag-urlhelper"></a>
-
+# Module Jekyll::SeoTag::UrlHelper
 Mixin to share common URL-related methods between class
 

data/example/jekyll-seo-tag/Jekyll/SeoTag.md

@@ -1,11 +1,10 @@
-# Class Jekyll::SeoTag
 <a id="class-jekyll-seotag"></a>
+# Class Jekyll::SeoTag
 
 ### Constants
 
-#### `MINIFY_REGEX`
 <a id="MINIFY_REGEX"></a>
-
+#### `MINIFY_REGEX`
 Matches all whitespace that follows either
 
 ```
@@ -22,33 +21,28 @@ so that we do not interfere with the HTML comment at the
 very begining
 ```
 
-#### `VERSION`
 <a id="VERSION"></a>
-
+#### `VERSION`
 Not documented.
 
 ### Attributes
 
-#### `context` [RW]
 <a id="attribute-i-context"></a>
-
+#### `context` [RW]
 Not documented.
 
 ### Public Class Methods
 
-#### `new(_tag_name, text, _tokens)`
 <a id="method-c-new"></a>
-
+#### `new(_tag_name, text, _tokens)`
 Not documented.
 
-#### `template()`
 <a id="method-c-template"></a>
-
+#### `template()`
 Not documented.
 
 ### Public Instance Methods
 
-#### `render(context)`
 <a id="method-i-render"></a>
-
+#### `render(context)`
 Not documented.

data/example/jekyll-seo-tag/Jekyll.md

@@ -1,3 +1,3 @@
-# Module Jekyll
 <a id="module-jekyll"></a>
+# Module Jekyll
 

data/example/jekyll-seo-tag/Liquid/Tag.md

@@ -1,3 +1,3 @@
-# Class Liquid::Tag
 <a id="class-liquid-tag"></a>
+# Class Liquid::Tag
 

data/example/jekyll-seo-tag/Liquid.md

@@ -1,5 +1,4 @@
-# Module Liquid
 <a id="module-liquid"></a>
-
+# Module Liquid
 Prevent bundler errors
 

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

@@ -148,7 +148,11 @@ class RDoc::Generator::Markdown::RbsSignatureIndex
     Array(lines).select { |line| line&.match?(/\S/) }
   end
 
+  # Creates an immutable signature index.
+  #
   # @param signatures [Hash{Array => Array<String>}] Signature lookup.
+  #
+  # @return [void]
   def initialize(signatures)
     @signatures = signatures
   end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Preserves simple <pre class="ruby"> language metadata emitted by RDoc.
+class ReverseMarkdown::Converters::RDocMarkdownPre < ReverseMarkdown::Converters::Pre
+  # Matches RDoc's plain language class names on pre blocks.
+  LANGUAGE_CLASS = /\A(?!highlight\z)[A-Za-z][A-Za-z0-9_+-]*\z/
+
+  # Converts an RDoc pre block into a GitHub-flavored Markdown fence.
+  #
+  # @param node [Nokogiri::XML::Node] RDoc pre node.
+  # @param _state [Hash] reverse_markdown converter state.
+  #
+  # @return [String] Markdown code fence.
+  def convert(node, _state)
+    content = treat_children(rdoc_pre_node(node), {})
+    "\n```#{language(node)}\n" << content << "\n```\n"
+  end
+
+  private
+
+  # Rebuilds a plain pre node from RDoc-highlighted text.
+  #
+  # @param node [Nokogiri::XML::Node] RDoc pre node.
+  #
+  # @return [Nokogiri::XML::Node] Plain pre node.
+  def rdoc_pre_node(node)
+    Nokogiri::HTML.fragment("<pre>#{node.text}</pre>").at("pre")
+  end
+
+  # Extracts the Markdown fence language.
+  #
+  # @param node [Nokogiri::XML::Node] RDoc pre node.
+  #
+  # @return [String, nil] Language name, or nil when no language is known.
+  def language(node)
+    node["class"].to_s[LANGUAGE_CLASS] || super
+  end
+end
+
+ReverseMarkdown::Converters.register :pre, ReverseMarkdown::Converters::RDocMarkdownPre.new

data/lib/rdoc/generator/markdown.rb

@@ -5,8 +5,8 @@ gem "rdoc"
 require "erb"
 require "reverse_markdown"
 require "csv"
-require "cgi"
 require "optparse"
+require_relative "markdown/rdoc_markdown_pre"
 
 # Generates Markdown output and a CSV search index from an RDoc store.
 class RDoc::Generator::Markdown
@@ -315,9 +315,7 @@ class RDoc::Generator::Markdown
     # - bypass - Ignore the unknown tag but try to convert its content
     # - raise - Raise an error to let you know
 
-    html = normalize_rdoc_pre_blocks(input)
-
-    md = ReverseMarkdown.convert(html, github_flavored: true, unknown_tags: @markdown_unknown_tags).dup
+    md = ReverseMarkdown.convert(input, github_flavored: true, unknown_tags: @markdown_unknown_tags).dup
 
     # Flatten headings whose visible text is wrapped in a self-link.
     md.gsub!(/^(#+)\s\[([^\]]+)\]\((?:#[^)]+)\)$/) { "#{Regexp.last_match(1)} #{Regexp.last_match(2)}" }
@@ -574,7 +572,7 @@ class RDoc::Generator::Markdown
   #
   # @return [String] Markdown with convertible blocks normalized.
   def normalize_definition_list_code_blocks(markdown)
-    markdown.gsub(/```\n(.+?)\n```/m) do
+    markdown.gsub(/```[^\n]*\n(.+?)\n```/m) do
       body = Regexp.last_match(1)
       converted = convert_definition_list_block(body)
       converted.nil? ? Regexp.last_match : converted
@@ -622,19 +620,6 @@ class RDoc::Generator::Markdown
     "#{output_path_for(target_parent)}##{method.aref}"
   end
 
-  # Removes RDoc's generated HTML tags from verbatim pre blocks.
-  #
-  # @param html [String] RDoc HTML fragment.
-  #
-  # @return [String] HTML fragment with normalized pre blocks.
-  def normalize_rdoc_pre_blocks(html)
-    html.gsub(%r{<pre\b[^>]*>(?:.+?)</pre>}m) do
-      raw = Regexp.last_match(0)
-      text = raw.gsub(/<[^>]+>/, "")
-      "<pre>#{CGI.unescapeHTML(text)}</pre>"
-    end
-  end
-
   # Rewrites local Markdown links relative to the current output file.
   #
   # @param markdown [String] Markdown content.

data/lib/rdoc/markdown/version.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
+# @private
 module Rdoc
+  # @private
   module Markdown
-    VERSION = "0.10.3"
+    # @private
+    VERSION = "0.11.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -1,4 +1,5 @@
-# <%= klass.type.capitalize %> <%= display_name(klass) %> <%= anchor(klass.aref.strip) %>
+<%= anchor(klass.aref.strip) %>
+# <%= klass.type.capitalize %> <%= display_name(klass) %>
 <%- class_description = describe(klass) -%>
 <%- unless class_description.empty? -%>
 <%= class_description %>
@@ -20,7 +21,8 @@
 ### Constants
 <% constants.sort_by(&:name).each do |const| -%>
 
-#### `<%= const.name %>` <%= anchor(const.name) %>
+<%= anchor(const.name) %>
+#### `<%= const.name %>`
 <%= describe(const, fallback: "Not documented.", heading_level_offset: 4) %>
 <% end -%>
 <%- end -%>
@@ -29,7 +31,8 @@
 ### Attributes
 <% attributes.sort_by(&:name).each do |attr| -%>
 
-#### `<%= attr.name %>` [<%= attr.rw %>] <%= anchor(attr.aref.strip) %>
+<%= anchor(attr.aref.strip) %>
+#### `<%= attr.name %>` [<%= attr.rw %>]
 <%= describe(attr, fallback: "Not documented.", heading_level_offset: 4) %>
 <% end -%>
 <%- end -%>
@@ -41,7 +44,8 @@
 ### <%= visibility.capitalize %> <%= type.capitalize %> Methods
 <% methods.each do |method| -%>
 
-#### `<%= method.name %><%= method_signature(method) %>` <%= anchor(method.aref) %>
+<%= anchor(method.aref) %>
+#### `<%= method.name %><%= method_signature(method) %>`
 <%= method_description(method, current_class: klass) %>
 <% end -%>
 <% end -%>

data/mutant.yml

@@ -13,3 +13,4 @@ requires:
 matcher:
   subjects:
     - RDoc::Generator::Markdown*
+    - ReverseMarkdown::Converters::RDocMarkdownPre*

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.11.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -224,6 +224,7 @@ files:
 - lib/rdoc/discover.rb
 - lib/rdoc/generator/markdown.rb
 - lib/rdoc/generator/markdown/rbs_signature_index.rb
+- lib/rdoc/generator/markdown/rdoc_markdown_pre.rb
 - lib/rdoc/markdown/version.rb
 - lib/templates/classfile.md.erb
 - mutant.yml