rdoc-markdown 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8e35102f73fbebb99a831ca7e2210b41c065177ae7c637e86cffb61094560b7
-  data.tar.gz: 44d35c36100b1488c2d5c5c689239b0d4ce6ae5f151fcc0ba3dec64f17cb97ac
+  metadata.gz: 35702d5815f56256651a8994111e772ee761a19a0df97052816431c15247b73b
+  data.tar.gz: 3720a080b24825ea96ea487d5b264dcbe2cf2f4c5e8ea25be677e9c54a0b0f4e
 SHA512:
-  metadata.gz: c54de4099d5966da00719ef1fd7fafe9a9a15823d4e55e6b38489d32bacb366a9ee9b2ea1a8a85500bb8da29bd466bc00853cde0ad65c4f984e052652c35b52a
-  data.tar.gz: c08fbcf88edcd97e665def817f22d56113885a37b77ad471f26dfd72e6485912641018c3ab46261e0d019a58d24f007a2c8a480e166c8533432bf9a642500e8a
+  metadata.gz: de2608fb5a61247ef9fd33153a8ab75bbfb21b9e3200078a1d59237340a0511cbee0866e90dce2d4a6d73408aed16bd2bb53e09f3e78118c083dd388b411c366
+  data.tar.gz: d5c8e5de4664c1300b8997c13948b296bd2ed39768396f5a5928cfea176f91130b51359f8ee982e24f2ef2a5284b10f53c2c4dbb6249d0e3726f9225a0e1212c

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.8.0
+
+### Added
+- Add `markdown_unknown_tags` RDoc option to configure reverse_markdown unknown tag handling
+
+### Changed
+- Fail before generation when RDoc supplies a non-string output directory
+- Markdown template will only include visible classes/module/methods, same as rdoc does with HTML templates
+
 ## 0.7.0
 
 ### Changed

data/Gemfile.lock

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

data/README.md

@@ -1,10 +1,15 @@
 # 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. I heavily rely on Obsidian to render my storage of markdown notes. But markdown is used not just for scribbles, supported is far and wide. We can render markdown file on any device, probably even on thermometer with a screen. But also everyone knows enough markdown to be dangerous (or productive).
+Markdown has become the de-facto documentation standard. We can render markdown file on any device, possibly on thermometer with a screen. And everyone knows markdown...
 
-It's a pitty that rdoc and yard can't output a proper markdown file. I would like to change that.
+It's a pitty that rdoc can't output a proper markdown file. Somebody has to try and build it.
 
 ## Installation
 
@@ -16,7 +21,7 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install rdoc-markdown
 ## Examples
-Find examples in [/examples](/example/) folder. You can regenerate examples by running `./bin/generate.sh`, it will produce examples based on file in `test/data/*` folder.
+Find examples in [/example](/example/) folder. You can regenerate examples by running `./bin/generate.sh`; it produces the sample docs from `test/data/example.rb` and a pinned `jekyll-seo-tag` example from `vendor/jekyll-seo-tag`.
 
 
 ## Usage
@@ -28,6 +33,22 @@ Run following command in directory with ruby source code:
 
 This will produce a tree of markdown documents and search index in `/doc` folder. Every class in library will have it's own markdown file.
 
+### Unknown HTML tags
+rdoc-markdown uses `reverse_markdown` to convert RDoc's HTML fragments to Markdown. You can configure how unknown HTML tags are handled with:
+
+```sh
+rdoc --format=markdown --markdown-unknown-tags=raise
+```
+
+Accepted values are `pass_through`, `drop`, `bypass`, and `raise`. The default is `pass_through`, which matches `reverse_markdown`'s default behavior.
+
+The same setting can be stored in RDoc's `.rdoc_options` file:
+
+```yaml
+---
+markdown_unknown_tags: :raise
+```
+
 ## Note on index.csv file
 This gem emits index of all markdown files in a index.csv file.
 
@@ -70,6 +91,7 @@ This task validates:
 
 - generated sample docs,
 - checked-in `example/` docs,
+- generated `jekyll-seo-tag` docs,
 - vendored minitest docs,
 - vendored rails docs (Active Support, Active Record, Action Pack, Railties slices).
 
@@ -113,15 +135,17 @@ Use rake tasks to generate markdown output for vendored projects:
 
 ```
 rake vendor:setup
+rake vendor:docs:jekyll_seo_tag
 rake vendor:docs:minitest
 rake vendor:docs:rails
-# or generate both
+# or generate all
 rake vendor:docs
 ```
 
 Output is written to:
 
 - `vendor/docs/minitest`
+- `vendor/docs/jekyll-seo-tag`
 - `vendor/docs/rails`
 
 ## Release

data/Rakefile

@@ -5,6 +5,11 @@ require "rdoc/rdoc"
 require "rdoc/markdown"
 require_relative "test/support/markdown_validator"
 
+JEKYLL_SEO_TAG_NAME = "jekyll-seo-tag"
+JEKYLL_SEO_TAG_REF = "v2.8.0"
+JEKYLL_SEO_TAG_TITLE = "#{JEKYLL_SEO_TAG_NAME} #{JEKYLL_SEO_TAG_REF.delete_prefix("v")}"
+JEKYLL_SEO_TAG_VENDOR_PATH = "vendor/#{JEKYLL_SEO_TAG_NAME}"
+
 Rake::TestTask.new do |t|
   t.verbose = true
   t.warning = false
@@ -29,12 +34,7 @@ namespace :markdown do
     FileUtils.mkdir_p(validation_root)
 
     sample_output = File.join(validation_root, "sample")
-    generate_markdown_docs(
-      title: "sample",
-      root: File.expand_path("test/data", __dir__),
-      output: sample_output,
-      files: [File.expand_path("test/data/example.rb", __dir__)]
-    )
+    generate_sample_docs(output: sample_output)
 
     sample_count = MarkdownValidator.new(sample_output).validate!
     puts "Validated #{sample_count} markdown files in #{sample_output}"
@@ -59,6 +59,14 @@ namespace :markdown do
     puts "Validated #{minitest_count} markdown files in #{minitest_output}"
     puts "Skipped #{minitest_validator.unresolved_links} unresolved local links in vendored minitest docs"
 
+    Rake::Task["vendor:setup:jekyll_seo_tag"].invoke
+    jekyll_seo_tag_output = File.join(validation_root, JEKYLL_SEO_TAG_NAME)
+    generate_jekyll_seo_tag_docs(output: jekyll_seo_tag_output)
+    jekyll_seo_tag_validator = MarkdownValidator.new(jekyll_seo_tag_output, strict_links: strict_vendor_links)
+    jekyll_seo_tag_count = jekyll_seo_tag_validator.validate!
+    puts "Validated #{jekyll_seo_tag_count} markdown files in #{jekyll_seo_tag_output}"
+    puts "Skipped #{jekyll_seo_tag_validator.unresolved_links} unresolved local links in vendored jekyll-seo-tag docs"
+
     Rake::Task["vendor:setup:rails"].invoke
     rails_root = File.expand_path("vendor/rails", __dir__)
     rails_output = File.join(validation_root, "rails")
@@ -107,6 +115,56 @@ def generate_markdown_docs(title:, root:, output:, files:)
   RDoc::RDoc.new.document(options)
 end
 
+def generate_sample_docs(output:)
+  generate_markdown_docs(
+    title: "sample",
+    root: File.expand_path("test/data", __dir__),
+    output: output,
+    files: [File.expand_path("test/data/example.rb", __dir__)]
+  )
+end
+
+def jekyll_seo_tag_root
+  File.expand_path(JEKYLL_SEO_TAG_VENDOR_PATH, __dir__)
+end
+
+def generate_jekyll_seo_tag_docs(output:)
+  root = jekyll_seo_tag_root
+  unless Dir.exist?(root)
+    raise "Missing #{JEKYLL_SEO_TAG_VENDOR_PATH}. Run `rake vendor:setup:jekyll_seo_tag` first."
+  end
+
+  generate_markdown_docs(
+    title: JEKYLL_SEO_TAG_TITLE,
+    root: root,
+    output: output,
+    files: Dir[File.join(root, "lib/**/*.rb")].uniq
+  )
+end
+
+namespace :examples do
+  desc "Generate checked-in example markdown docs"
+  task :generate do
+    Rake::Task["vendor:setup:jekyll_seo_tag"].invoke
+
+    sample_output = File.expand_path("example", __dir__)
+    staging_root = File.expand_path("tmp/examples-generate", __dir__)
+    staged_sample_output = File.join(staging_root, "example")
+
+    FileUtils.rm_rf(staging_root)
+    generate_sample_docs(output: staged_sample_output)
+    generate_jekyll_seo_tag_docs(output: File.join(staged_sample_output, JEKYLL_SEO_TAG_NAME))
+
+    FileUtils.rm_rf(sample_output)
+    FileUtils.mv(staged_sample_output, sample_output)
+
+    puts "Generated sample markdown docs in #{sample_output}"
+    puts "Generated #{JEKYLL_SEO_TAG_NAME} markdown docs in #{File.join(sample_output, JEKYLL_SEO_TAG_NAME)}"
+  ensure
+    FileUtils.rm_rf(staging_root) if staging_root
+  end
+end
+
 def minitest_docs_files(root)
   files = Dir[File.join(root, "lib/**/*.rb")]
   files.concat(Dir[File.join(root, "*.rdoc")])
@@ -138,6 +196,19 @@ namespace :vendor do
     minitest_ref = "v6.0.1"
     rails_ref = ENV.fetch("RAILS_REF", "main")
 
+    desc "Clone/update vendor/jekyll-seo-tag and checkout docs-aligned tag"
+    task :jekyll_seo_tag do
+      ensure_git_checkout(
+        path: JEKYLL_SEO_TAG_VENDOR_PATH,
+        url: "https://github.com/jekyll/jekyll-seo-tag.git",
+        ref: JEKYLL_SEO_TAG_REF
+      )
+      Dir.chdir(JEKYLL_SEO_TAG_VENDOR_PATH) do
+        sh "git fetch --tags --force"
+        sh "git checkout #{JEKYLL_SEO_TAG_REF}"
+      end
+    end
+
     desc "Clone/update vendor/minitest and checkout docs-aligned tag"
     task :minitest do
       ensure_git_checkout(path: "vendor/minitest", url: "https://github.com/minitest/minitest.git", ref: minitest_ref)
@@ -151,9 +222,16 @@ namespace :vendor do
   end
 
   desc "Prepare all vendored repositories"
-  task setup: ["vendor:setup:minitest", "vendor:setup:rails"]
+  task setup: ["vendor:setup:jekyll_seo_tag", "vendor:setup:minitest", "vendor:setup:rails"]
 
   namespace :docs do
+    desc "Generate markdown docs for vendored jekyll-seo-tag"
+    task :jekyll_seo_tag do
+      output = File.expand_path("vendor/docs/#{JEKYLL_SEO_TAG_NAME}", __dir__)
+      generate_jekyll_seo_tag_docs(output: output)
+      puts "Generated #{JEKYLL_SEO_TAG_NAME} markdown docs in #{output}"
+    end
+
     desc "Generate markdown docs for vendored minitest"
     task :minitest do
       root = File.expand_path("vendor/minitest", __dir__)
@@ -180,7 +258,7 @@ namespace :vendor do
     end
 
     desc "Generate markdown docs for all vendored repositories"
-    task all: [:minitest, :rails]
+    task all: [:jekyll_seo_tag, :minitest, :rails]
   end
 
   desc "Generate markdown docs for all vendored repositories"

data/example/Bird.md

@@ -1,5 +1,5 @@
 # Class Bird
-<a id="class-Bird"></a>
+<a id="class-bird"></a>
 
 The base class for all birds.
 

data/example/Duck.md

@@ -1,5 +1,5 @@
 # Class Duck
-<a id="class-Duck"></a>
+<a id="class-duck"></a>
 
 A duck is a [`Waterfowl`](Waterfowl.md) [`Bird`](Bird.md).
 

data/example/Object.md

@@ -1,5 +1,5 @@
 # Class Object
-<a id="class-Object"></a>
+<a id="class-object"></a>
 
 ### Constants
 

data/example/Waterfowl.md

@@ -1,5 +1,5 @@
 # Module Waterfowl
-<a id="module-Waterfowl"></a>
+<a id="module-waterfowl"></a>
 
 A mixin for waterfowl creatures.
 

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

@@ -0,0 +1,40 @@
+# Class Jekyll::SeoTag::AuthorDrop
+<a id="class-jekyll-seotag-authordrop"></a>
+
+A drop representing the current page’s author
+
+Author name will be pulled from:
+
+1. The page’s `author` key
+
+2. The first author in the page’s `authors` key
+
+3. The `author` key in the site config
+
+If the result from the name search is a string, we’ll also check for additional author metadata in `site.data.authors`
+
+### Public Class Methods
+
+#### `new(page: nil, site: nil)`
+<a id="method-c-new"></a>
+
+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>
+
+[`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>
+
+Alias for: [`name`](#method-i-name)
+
+#### `twitter()`
+<a id="method-i-twitter"></a>
+
+Not documented.

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

@@ -0,0 +1,133 @@
+# Class Jekyll::SeoTag::Drop
+<a id="class-jekyll-seotag-drop"></a>
+
+### Constants
+
+#### `FORMAT_STRING_METHODS`
+<a id="FORMAT_STRING_METHODS"></a>
+
+Not documented.
+
+#### `HOMEPAGE_OR_ABOUT_REGEX`
+<a id="HOMEPAGE_OR_ABOUT_REGEX"></a>
+
+Not documented.
+
+#### `TITLE_SEPARATOR`
+<a id="TITLE_SEPARATOR"></a>
+
+Not documented.
+
+### Public Class Methods
+
+#### `new(text, context)`
+<a id="method-c-new"></a>
+
+Not documented.
+
+### Public Instance Methods
+
+#### `author()`
+<a id="method-i-author"></a>
+
+A drop representing the page author
+
+#### `canonical_url()`
+<a id="method-i-canonical_url"></a>
+
+Not documented.
+
+#### `date_modified()`
+<a id="method-i-date_modified"></a>
+
+Not documented.
+
+#### `date_published()`
+<a id="method-i-date_published"></a>
+
+Not documented.
+
+#### `description()`
+<a id="method-i-description"></a>
+
+Not documented.
+
+#### `image()`
+<a id="method-i-image"></a>
+
+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>
+
+A drop representing the JSON-LD output
+
+#### `links()`
+<a id="method-i-links"></a>
+
+Not documented.
+
+#### `logo()`
+<a id="method-i-logo"></a>
+
+Not documented.
+
+#### `name()`
+<a id="method-i-name"></a>
+
+rubocop:enable Metrics/CyclomaticComplexity
+
+#### `page_lang()`
+<a id="method-i-page_lang"></a>
+
+Not documented.
+
+#### `page_locale()`
+<a id="method-i-page_locale"></a>
+
+Not documented.
+
+#### `page_title()`
+<a id="method-i-page_title"></a>
+
+Page title without site title or description appended
+
+#### `site_description()`
+<a id="method-i-site_description"></a>
+
+Not documented.
+
+#### `site_tagline()`
+<a id="method-i-site_tagline"></a>
+
+Not documented.
+
+#### `site_tagline_or_description()`
+<a id="method-i-site_tagline_or_description"></a>
+
+Not documented.
+
+#### `site_title()`
+<a id="method-i-site_title"></a>
+
+Not documented.
+
+#### `title()`
+<a id="method-i-title"></a>
+
+Page title with site title or description appended rubocop:disable Metrics/CyclomaticComplexity
+
+#### `title?()`
+<a id="method-i-title-3F"></a>
+
+Should the ‘\<title\>` tag be generated for this page?
+
+#### `type()`
+<a id="method-i-type"></a>
+
+Not documented.
+
+#### `version()`
+<a id="method-i-version"></a>
+
+Not documented.

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

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

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

@@ -0,0 +1,33 @@
+# Class Jekyll::SeoTag::ImageDrop
+<a id="class-jekyll-seotag-imagedrop"></a>
+
+A drop representing the page image The image path will be pulled from:
+
+1. The `image` key if it’s a string
+
+2. The `image.path` key if it’s a hash
+
+3. The `image.facebook` key
+
+4. The `image.twitter` key
+
+### Public Class Methods
+
+#### `new(page: nil, context: nil)`
+<a id="method-c-new"></a>
+
+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>
+
+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>
+
+Alias for: [`path`](#method-i-path)

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

@@ -0,0 +1,18 @@
+# Module Jekyll::SeoTag::JSONLD
+<a id="module-jekyll-seotag-jsonld"></a>
+
+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>
+
+Not documented.
+
+### Public Instance Methods
+
+#### `json_ld()`
+<a id="method-i-json_ld"></a>
+
+Self should be a [`Jekyll::SeoTag::Drop`](Drop.md) instance (when extending the module)

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

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

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

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

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

@@ -0,0 +1,54 @@
+# Class Jekyll::SeoTag
+<a id="class-jekyll-seotag"></a>
+
+### Constants
+
+#### `MINIFY_REGEX`
+<a id="MINIFY_REGEX"></a>
+
+Matches all whitespace that follows either
+
+```
+1. A '}', which closes a Liquid tag
+2. A '{', which opens a JSON block
+3. A '>' followed by a newline, which closes an XML tag or
+4. A ',' followed by a newline, which ends a JSON line
+```
+
+We will strip all of this whitespace to minify the template We will not strip any whitespace if the next character is a ‘-’
+
+```
+so that we do not interfere with the HTML comment at the
+very begining
+```
+
+#### `VERSION`
+<a id="VERSION"></a>
+
+Not documented.
+
+### Attributes
+
+#### `context` [RW]
+<a id="attribute-i-context"></a>
+
+Not documented.
+
+### Public Class Methods
+
+#### `new(_tag_name, text, _tokens)`
+<a id="method-c-new"></a>
+
+Not documented.
+
+#### `template()`
+<a id="method-c-template"></a>
+
+Not documented.
+
+### Public Instance Methods
+
+#### `render(context)`
+<a id="method-i-render"></a>
+
+Not documented.

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

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

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

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

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

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

data/example/jekyll-seo-tag/index.csv

@@ -0,0 +1,60 @@
+name,type,path
+Jekyll,Module,Jekyll.md
+Jekyll::SeoTag,Class,Jekyll/SeoTag.md
+Jekyll::SeoTag.new,Method,Jekyll/SeoTag.md#method-c-new
+Jekyll::SeoTag.render,Method,Jekyll/SeoTag.md#method-i-render
+Jekyll::SeoTag.template,Method,Jekyll/SeoTag.md#method-c-template
+Jekyll::SeoTag.MINIFY_REGEX,Constant,Jekyll/SeoTag.md#MINIFY_REGEX
+Jekyll::SeoTag.VERSION,Constant,Jekyll/SeoTag.md#VERSION
+Jekyll::SeoTag.context,Attribute,Jekyll/SeoTag.md#attribute-i-context
+Jekyll::SeoTag::AuthorDrop,Class,Jekyll/SeoTag/AuthorDrop.md
+Jekyll::SeoTag::AuthorDrop.new,Method,Jekyll/SeoTag/AuthorDrop.md#method-c-new
+Jekyll::SeoTag::AuthorDrop.name,Method,Jekyll/SeoTag/AuthorDrop.md#method-i-name
+Jekyll::SeoTag::AuthorDrop.to_s,Method,Jekyll/SeoTag/AuthorDrop.md#method-i-to_s
+Jekyll::SeoTag::AuthorDrop.twitter,Method,Jekyll/SeoTag/AuthorDrop.md#method-i-twitter
+Jekyll::SeoTag::Drop,Class,Jekyll/SeoTag/Drop.md
+Jekyll::SeoTag::Drop.new,Method,Jekyll/SeoTag/Drop.md#method-c-new
+Jekyll::SeoTag::Drop.version,Method,Jekyll/SeoTag/Drop.md#method-i-version
+Jekyll::SeoTag::Drop.title?,Method,Jekyll/SeoTag/Drop.md#method-i-title-3F
+Jekyll::SeoTag::Drop.site_title,Method,Jekyll/SeoTag/Drop.md#method-i-site_title
+Jekyll::SeoTag::Drop.site_tagline,Method,Jekyll/SeoTag/Drop.md#method-i-site_tagline
+Jekyll::SeoTag::Drop.site_description,Method,Jekyll/SeoTag/Drop.md#method-i-site_description
+Jekyll::SeoTag::Drop.page_title,Method,Jekyll/SeoTag/Drop.md#method-i-page_title
+Jekyll::SeoTag::Drop.site_tagline_or_description,Method,Jekyll/SeoTag/Drop.md#method-i-site_tagline_or_description
+Jekyll::SeoTag::Drop.title,Method,Jekyll/SeoTag/Drop.md#method-i-title
+Jekyll::SeoTag::Drop.name,Method,Jekyll/SeoTag/Drop.md#method-i-name
+Jekyll::SeoTag::Drop.description,Method,Jekyll/SeoTag/Drop.md#method-i-description
+Jekyll::SeoTag::Drop.author,Method,Jekyll/SeoTag/Drop.md#method-i-author
+Jekyll::SeoTag::Drop.json_ld,Method,Jekyll/SeoTag/Drop.md#method-i-json_ld
+Jekyll::SeoTag::Drop.image,Method,Jekyll/SeoTag/Drop.md#method-i-image
+Jekyll::SeoTag::Drop.date_modified,Method,Jekyll/SeoTag/Drop.md#method-i-date_modified
+Jekyll::SeoTag::Drop.date_published,Method,Jekyll/SeoTag/Drop.md#method-i-date_published
+Jekyll::SeoTag::Drop.type,Method,Jekyll/SeoTag/Drop.md#method-i-type
+Jekyll::SeoTag::Drop.links,Method,Jekyll/SeoTag/Drop.md#method-i-links
+Jekyll::SeoTag::Drop.logo,Method,Jekyll/SeoTag/Drop.md#method-i-logo
+Jekyll::SeoTag::Drop.page_lang,Method,Jekyll/SeoTag/Drop.md#method-i-page_lang
+Jekyll::SeoTag::Drop.page_locale,Method,Jekyll/SeoTag/Drop.md#method-i-page_locale
+Jekyll::SeoTag::Drop.canonical_url,Method,Jekyll/SeoTag/Drop.md#method-i-canonical_url
+Jekyll::SeoTag::Drop.FORMAT_STRING_METHODS,Constant,Jekyll/SeoTag/Drop.md#FORMAT_STRING_METHODS
+Jekyll::SeoTag::Drop.HOMEPAGE_OR_ABOUT_REGEX,Constant,Jekyll/SeoTag/Drop.md#HOMEPAGE_OR_ABOUT_REGEX
+Jekyll::SeoTag::Drop.TITLE_SEPARATOR,Constant,Jekyll/SeoTag/Drop.md#TITLE_SEPARATOR
+Jekyll::SeoTag::Filters,Class,Jekyll/SeoTag/Filters.md
+Jekyll::SeoTag::Filters.new,Method,Jekyll/SeoTag/Filters.md#method-c-new
+Jekyll::SeoTag::ImageDrop,Class,Jekyll/SeoTag/ImageDrop.md
+Jekyll::SeoTag::ImageDrop.new,Method,Jekyll/SeoTag/ImageDrop.md#method-c-new
+Jekyll::SeoTag::ImageDrop.path,Method,Jekyll/SeoTag/ImageDrop.md#method-i-path
+Jekyll::SeoTag::ImageDrop.to_s,Method,Jekyll/SeoTag/ImageDrop.md#method-i-to_s
+Jekyll::SeoTag::JSONLD,Module,Jekyll/SeoTag/JSONLD.md
+Jekyll::SeoTag::JSONLD.json_ld,Method,Jekyll/SeoTag/JSONLD.md#method-i-json_ld
+Jekyll::SeoTag::JSONLD.METHODS_KEYS,Constant,Jekyll/SeoTag/JSONLD.md#METHODS_KEYS
+Jekyll::SeoTag::JSONLDDrop,Class,Jekyll/SeoTag/JSONLDDrop.md
+Jekyll::SeoTag::JSONLDDrop.new,Method,Jekyll/SeoTag/JSONLDDrop.md#method-c-new
+Jekyll::SeoTag::JSONLDDrop.fallback_data,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-fallback_data
+Jekyll::SeoTag::JSONLDDrop.author,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-author
+Jekyll::SeoTag::JSONLDDrop.image,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-image
+Jekyll::SeoTag::JSONLDDrop.publisher,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-publisher
+Jekyll::SeoTag::JSONLDDrop.mainEntityOfPage,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-mainEntityOfPage
+Jekyll::SeoTag::JSONLDDrop.to_json,Method,Jekyll/SeoTag/JSONLDDrop.md#method-i-to_json
+Jekyll::SeoTag::UrlHelper,Module,Jekyll/SeoTag/UrlHelper.md
+Liquid,Module,Liquid.md
+Liquid::Tag,Class,Liquid/Tag.md

data/lib/rdoc/generator/markdown.rb

@@ -6,6 +6,7 @@ require "erb"
 require "reverse_markdown"
 require "csv"
 require "cgi"
+require "optparse"
 
 # Generates Markdown output and a CSV search index from an RDoc store.
 class RDoc::Generator::Markdown
@@ -14,6 +15,67 @@ class RDoc::Generator::Markdown
   # Directory containing ERB templates.
   TEMPLATE_DIR = File.expand_path(File.join(File.dirname(__FILE__), "..", "..", "templates"))
 
+  # Supported reverse_markdown unknown-tag modes.
+  MARKDOWN_UNKNOWN_TAGS = %i[pass_through drop bypass raise].freeze
+
+  # Adds rdoc-markdown generator configuration to RDoc's option object.
+  module OptionsExtension
+    # Initializes markdown generator options alongside RDoc's built-in options.
+    #
+    # @return [void]
+    def init_ivars
+      super
+      @markdown_unknown_tags = :pass_through
+    end
+
+    # Loads markdown generator options from serialized RDoc options.
+    #
+    # @param map [Psych::Coder] Serialized RDoc options.
+    #
+    # @return [void]
+    def init_with(map)
+      super
+      @markdown_unknown_tags = map["markdown_unknown_tags"] if map.map.key?("markdown_unknown_tags")
+    end
+
+    # Applies markdown generator options from a loaded .rdoc_options hash.
+    #
+    # @param map [Hash] Loaded RDoc options.
+    #
+    # @return [void]
+    def override(map)
+      super
+      @markdown_unknown_tags = map.fetch("markdown_unknown_tags") if map.key?("markdown_unknown_tags")
+    end
+  end
+
+  # Registers markdown generator-specific RDoc options.
+  #
+  # @param rdoc_options [RDoc::Options] RDoc options object.
+  #
+  # @return [void]
+  def self.setup_options(rdoc_options)
+    rdoc_options.option_parser.on(
+      "--markdown-unknown-tags=MODE",
+      "How to handle unknown HTML tags: #{MARKDOWN_UNKNOWN_TAGS.join(", ")}."
+    ) do |value|
+      rdoc_options.markdown_unknown_tags = value.to_sym
+    end
+  end
+
+  # Validates the configured reverse_markdown unknown-tag mode.
+  #
+  # @param value [Symbol] Unknown-tag mode.
+  #
+  # @return [Symbol] Validated unknown-tag mode.
+  def self.validate_markdown_unknown_tags(value)
+    return value if MARKDOWN_UNKNOWN_TAGS.include?(value)
+
+    expected = MARKDOWN_UNKNOWN_TAGS.map { |mode| ":#{mode}" }.join(", ")
+    raise OptionParser::InvalidArgument,
+      "invalid markdown_unknown_tags: #{value.inspect} (expected one of: #{expected})"
+  end
+
   # Source store for generated content.
   #
   # @return [RDoc::Store]
@@ -50,6 +112,7 @@ class RDoc::Generator::Markdown
   def initialize(store, rdoc_options)
     @store = store
     @options = rdoc_options
+    @markdown_unknown_tags = self.class.validate_markdown_unknown_tags(rdoc_options.markdown_unknown_tags)
 
     @base_dir = Pathname.pwd
   end
@@ -252,7 +315,7 @@ class RDoc::Generator::Markdown
 
     html = normalize_rdoc_pre_blocks(input)
 
-    md = ReverseMarkdown.convert(html, github_flavored: true)
+    md = ReverseMarkdown.convert(html, 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)}" }
@@ -636,7 +699,7 @@ class RDoc::Generator::Markdown
   def build_class_docs(classes)
     docs_by_name = {}
 
-    classes.each do |klass|
+    classes.select(&:display?).each do |klass|
       display_name = normalized_full_name(klass.full_name)
       output_path = turn_to_path(display_name)
       legacy_path = turn_to_path(klass.full_name)
@@ -666,9 +729,11 @@ class RDoc::Generator::Markdown
 
     docs_by_name.values
       .select do |doc|
+        klass = doc.fetch(:klass)
+
         doc.fetch(:score).positive? ||
-          !synthetic_full_name?(doc.fetch(:klass).full_name)
-    end
+          (!class_has_raw_members?(klass) && !synthetic_full_name?(klass.full_name))
+      end
       .sort_by { |doc| doc.fetch(:display_name) }
   end
 
@@ -695,17 +760,35 @@ class RDoc::Generator::Markdown
     normalized
   end
 
-  # Scores how much visible content a class or module has.
+  # Scores how much owned content a class or module has.
   #
   # @param klass [RDoc::Context] Class or module object.
   #
   # @return [Integer] Content score used to choose duplicate docs.
   def class_content_score(klass)
-    score = klass.method_list.size + klass.constants.size + klass.attributes.size
+    score = class_member_count(klass)
     score += 1 unless klass.description.empty?
     score
   end
 
+  # Counts methods, constants, and attributes owned by a class or module.
+  #
+  # @param klass [RDoc::Context] Class or module object.
+  #
+  # @return [Integer] Number of owned members.
+  def class_member_count(klass)
+    klass.method_list.count(&:display?) + klass.constants.count(&:display?) + klass.attributes.count(&:display?)
+  end
+
+  # Checks whether a class or module owns any members before display filtering.
+  #
+  # @param klass [RDoc::Context] Class or module object.
+  #
+  # @return [Boolean] True when any owned member exists before display filtering.
+  def class_has_raw_members?(klass)
+    klass.method_list.any? || klass.constants.any? || klass.attributes.any?
+  end
+
   # Checks whether a name appears to contain duplicated root namespaces.
   #
   # @param full_name [String] Full RDoc object name.
@@ -722,6 +805,9 @@ class RDoc::Generator::Markdown
   # @return [void]
   def setup
     @output_dir = @options.op_dir
+    unless @output_dir.instance_of?(String)
+      raise TypeError, "RDoc markdown output directory must be a String"
+    end
 
     @class_docs = build_class_docs(@store.all_classes_and_modules.sort)
     @class_docs_by_object_id = @class_docs.to_h { |doc| [doc.fetch(:klass).object_id, doc] }
@@ -738,3 +824,13 @@ class RDoc::Generator::Markdown
     @root_path_segment = Pathname.new(@options.root || ".").basename
   end
 end
+
+# RDoc configuration extended with markdown generator options.
+class RDoc::Options
+  prepend RDoc::Generator::Markdown::OptionsExtension
+
+  # Controls how reverse_markdown handles unknown HTML tags.
+  #
+  # @return [Symbol]
+  attr_accessor :markdown_unknown_tags
+end

data/lib/rdoc/markdown/version.rb

@@ -5,6 +5,6 @@ module Rdoc
   # Version namespace for rdoc-markdown.
   module Markdown
     # Current gem version.
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/templates/classfile.md.erb

@@ -41,6 +41,7 @@
 <%- end -%>
 <% klass.methods_by_type(section).each do |type, visibilities| -%>
 <% visibilities.each do |visibility, methods| -%>
+<% methods = methods.select(&:display?) -%>
 <% next if methods.empty? -%>
 
 ### <%= visibility.capitalize %> <%= type.capitalize %> Methods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rdoc-markdown
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -190,6 +190,18 @@ files:
 - example/Object.md
 - example/Waterfowl.md
 - example/index.csv
+- example/jekyll-seo-tag/Jekyll.md
+- example/jekyll-seo-tag/Jekyll/SeoTag.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/AuthorDrop.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/Drop.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/Filters.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/ImageDrop.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/JSONLD.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/JSONLDDrop.md
+- example/jekyll-seo-tag/Jekyll/SeoTag/UrlHelper.md
+- example/jekyll-seo-tag/Liquid.md
+- example/jekyll-seo-tag/Liquid/Tag.md
+- example/jekyll-seo-tag/index.csv
 - gemfiles/rdoc_head.gemfile
 - lib/markdown.rb
 - lib/rdoc/discover.rb