yard-markdown 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d0f4cb4021498fef4a2ae549af15357c6d2fa65e2099677e75d1b25920e680
-  data.tar.gz: 465def23d344679e869e776d856ce5a694e483d46dc5ab37fcf43eebe67f11cf
+  metadata.gz: 80c8051a8c7527055a46d9dcad2db56a019f54bb99315e25813a010152fd2df3
+  data.tar.gz: 7187cf79b4ea2ef53b859cb17971681eefc3981e2d3da9718dead415a2b503f2
 SHA512:
-  metadata.gz: c2c2c4b64ea40ec28ab122d2398f2cfc72823e35fbb6a50a16146b5cb5199c44df4431cd568c00917d1011812afdb6c2c4d5862eaa8a2e66a3288bb9a901b731
-  data.tar.gz: 63d188cab16ac36c3200205a01a0dd8f902061db68d2fdbc0ab81357de96cb478e44ae066e2ecd439978cba25c9ab60576aa385c0c496e32e9b3eec142de5e26
+  metadata.gz: 71b9f9638c8f7da302a2d8a412524bef3bb77aa7a0ec5f38a8cdc45fa04f4a65e34b0d6e7bb9c0b42e765c474041ec6b9a2845d7136f11552dd64e6f4fc52720
+  data.tar.gz: 6e1459ddb1e780dc708d67a1bc13d8f7315bfd8041a07c72207bf66af6bf4d9b91ce9833d7346ec78eef2708eff449932bb6d2743d4e64b8ea5bfe87d3d71e4a

data/CHANGELOG.md

@@ -5,6 +5,14 @@ This format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## Unreleased
 
+## 0.9.1
+
+- Include full filenames for files, not just titles
+
+## 0.9.0
+
+- Detect Markdown files, copy them into generated documentation, and include them in `index.csv`.
+
 ## 0.8.0
 
 - Adding metadata section

data/README.md

@@ -19,6 +19,16 @@ gem install yard-markdown
 
 Run `yardoc --format=markdown` to generate markdown documentation.
 
+Markdown files in the project tree are detected automatically, copied unchanged into the output, and listed in `index.csv`:
+
+Markdown files whose basename starts with `_` are ignored automatically.
+
+Use YARD's `--exclude` option to omit a separate documentation tree:
+
+```bash
+yardoc --format=markdown --exclude '\Adocs/'
+```
+
 ## FAQ
 
 ### Note on RDoc support
@@ -66,14 +76,14 @@ Validate generated markdown in sample docs:
 bundle exec rake markdown:validate_examples
 ```
 
-There is also a real-world validation harness for repositories with substantial YARD documentation (`rspec-core`, `sidekiq`):
+There is also a real-world validation harness for repositories with substantial YARD documentation (`faraday`, `sidekiq`):
 
 ```bash
 bundle exec rake markdown:validate_real_world
 ```
 
-This task validates generated markdown against CommonMark + GFM rendering, and reports unresolved local links found in upstream source comments while still validating local anchor/link structure.
+This task validates every generated Markdown file against CommonMark and GFM. Generated files must have valid local links and anchors; unresolved links and anchors in byte-identical Markdown copied from upstream are reported instead of failing validation.
 
-GitHub Actions CI now runs this task on every push/PR, so `sidekiq` and other real-world fixture gems are verified continuously.
+GitHub Actions CI runs this task on every push/PR, so both real-world fixture gems are verified continuously.
 
-For reproducible checks, the task clones pinned tags (`rspec-core` `v3.13.2`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` before generating output.
+For reproducible checks, the task clones pinned tags (`faraday` `v2.14.3`, `sidekiq` `v7.3.10`) into `tmp/real-world/repos` and honors each repository's `.yardopts` before generating output in `tmp/real-world/faraday` and `tmp/real-world/sidekiq`.

data/lib/yard/markdown/aref_helper.rb

@@ -10,7 +10,7 @@ module YARD
       #
       # @param value [Object] Raw anchor fragment to encode.
       # @return [String] Anchor-safe identifier fragment.
-      def anchor_component(value)
+      def self.anchor_component(value)
         value.to_s.each_char.map do |char|
           char.match?(/[A-Za-z0-9_-]/) ? char : format("-%X", char.ord)
         end.join
@@ -20,22 +20,41 @@ module YARD
       #
       # @param object [YARD::CodeObjects::Base] Object being rendered.
       # @return [String] Anchor id for the object's heading.
-      def aref(object)
-        type = object.type
-
-        return "class-#{object.path.gsub("::", "-")}" if type == :class
-        return "module-#{object.path.gsub("::", "-")}" if type == :module
-        return "constant-#{object.name}" if type == :constant
-        return "classvariable-#{anchor_component(object.name)}" if type == :classvariable
-
-        scope = (object.scope == :class) ? "c" : "i"
+      def self.aref(object)
+        aref_for(object, object.type, object.name)
+      end
 
-        if !object.attr_info.nil?
-          "attribute-#{scope}-#{object.name}"
+      # Dispatches anchor formatting using preloaded object attributes.
+      #
+      # @param object [YARD::CodeObjects::Base] Object being rendered.
+      # @param type [Symbol] YARD object type.
+      # @param name [String, Symbol] Object name.
+      # @return [String] Anchor id for the object's heading.
+      def self.aref_for(object, type, name)
+        case type
+        when :class, :module
+          "#{type}-#{object.path.gsub("::", "-")}"
+        when :constant
+          "constant-#{name}"
+        when :classvariable
+          "classvariable-#{anchor_component(name)}"
         else
-          "method-#{scope}-#{anchor_component(object.name)}"
+          callable_aref(object, name)
         end
       end
+      private_class_method :aref_for
+
+      # Returns the anchor id for a method or attribute.
+      #
+      # @param object [YARD::CodeObjects::MethodObject] Method or attribute being rendered.
+      # @param name [String, Symbol] Method or attribute name.
+      # @return [String] Anchor id for the callable object's heading.
+      def self.callable_aref(object, name)
+        scope = (object.scope == :class) ? "c" : "i"
+        kind, name = object.attr_info ? ["attribute", name] : ["method", anchor_component(name)]
+        "#{kind}-#{scope}-#{name}"
+      end
+      private_class_method :callable_aref
     end
   end
 end

data/lib/yard/markdown/collection_rendering_helper.rb

@@ -10,7 +10,7 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the constants section.
       def render_constants(constants, group_order)
-        render_collection("Constants", constants.sort_by { |item| item.name }, group_order) { |item| "`#{item.name}`" }
+        render_collection("Constants", constants.sort_by(&:name), group_order) { |item| "`#{item.name}`" }
       end
 
       # Renders the attributes section for an object page.
@@ -19,7 +19,7 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the attributes section.
       def render_attributes(attrs, group_order)
-        render_collection("Attributes", attrs, group_order) { |item| "`#{item.name}` [#{attribute_access(item)}]" }
+        render_collection("Attributes", attrs, group_order) { |item| "`#{item.name}` [#{MethodPresentationHelper.attribute_access(item)}]" }
       end
 
       # Renders a method section for an object page.
@@ -29,7 +29,7 @@ module YARD
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
       # @return [String] Markdown for the method section.
       def render_methods(section_title, methods, group_order)
-        render_collection(section_title, methods, group_order) { |item| "`#{formatted_method_heading(item)}`" }
+        render_collection(section_title, methods, group_order) { |item| "`#{MethodPresentationHelper.formatted_method_heading(item)}`" }
       end
 
       # Renders a grouped collection with a caller-provided item label.
@@ -37,25 +37,36 @@ module YARD
       # @param section_title [String] Section title to render.
       # @param items [Array<YARD::CodeObjects::Base>] Objects to group and render.
       # @param group_order [Array<String>, nil] Preferred ordering for group headings.
+      # @param label [Proc] Item-label renderer.
+      # @yieldparam item [YARD::CodeObjects::Base] Object whose label should be rendered.
       # @return [String] Markdown for the collection section.
-      def render_collection(section_title, items, group_order)
-        lines = ["## #{section_title}"]
-        groups = grouped_items(items, group_order)
-        uses_groups = groups.any? { |name, _items| !name.nil? }
-        item_heading = uses_groups ? "####" : "###"
+      def render_collection(section_title, items, group_order, &label)
+        groups = SectionAssemblyHelper.grouped_items(items, group_order)
+        grouped = groups.any? { |name, _items| name }
+        body = groups.map do |name, group_items|
+          item_heading = grouped ? "####" : "###"
+          item_markdown = group_items.map { |item| render_collection_item(item_heading, item, &label) }.join("\n\n")
+          [("### #{name || "General"}" if grouped), item_markdown].compact
+        end
 
-        groups.each do |group_name, group_items|
-          lines << "### #{group_name || "General"}" if uses_groups
+        ["## #{section_title}", body].join("\n")
+      end
 
-          lines << group_items.map { |item|
-            item_lines = [heading_with_anchors("#{item_heading} #{yield(item)}", item)]
-            append_lines(item_lines, documented_text(item), separated: false)
-            append_lines(item_lines, render_tags(item), separated: false)
-            item_lines.join("\n")
-          }.join("\n\n")
-        end
+      private
 
-        lines.join("\n")
+      # Renders one collection item with documentation and tags.
+      #
+      # @param item_heading [String] Markdown heading prefix for the item.
+      # @param item [YARD::CodeObjects::Base] Object being rendered.
+      # @param label [Proc] Item-label renderer.
+      # @yieldparam item [YARD::CodeObjects::Base] Object whose label should be rendered.
+      # @return [String] Rendered item Markdown.
+      def render_collection_item(item_heading, item, &label)
+        [
+          heading_with_anchors(item_heading + " " + label.call(item), item),
+          documented_text(item),
+          TagFormattingHelper.render_tags(item)
+        ].reject(&:empty?).join("\n")
       end
     end
   end

data/lib/yard/markdown/documentation_helper.rb

@@ -13,9 +13,8 @@ module YARD
       def documented_text(object)
         text = rdoc_to_md(object.docstring)
         return text unless text.empty?
-        return "" unless object.tags.empty?
 
-        "Not documented."
+        object.tags.empty? ? "Not documented." : ""
       end
 
       # Converts an RDoc-formatted docstring to Markdown.
@@ -25,17 +24,35 @@ module YARD
       def rdoc_to_md(docstring)
         fenced_code_blocks = []
         placeholder = "YARD_MARKDOWN_FENCED_CODE_BLOCK_%d"
-        content = docstring.gsub(/^```[^\n]*\n.*?^```[ \t]*$/m) do |block|
-          fenced_code_blocks << block
-          format(placeholder, fenced_code_blocks.length - 1)
-        end
-
+        content = extract_fenced_code_blocks(docstring, fenced_code_blocks, placeholder)
         markdown = RDoc::Markup::ToMarkdown.new.convert(content).rstrip
-        fenced_code_blocks.each_with_index do |block, index|
-          markdown = markdown.sub(format(placeholder, index), block)
+        restore_fenced_code_blocks(markdown, fenced_code_blocks, placeholder)
+      end
+
+      private
+
+      # Replaces fenced blocks with placeholders before RDoc conversion.
+      #
+      # @param docstring [String] Raw documentation text.
+      # @param fenced_code_blocks [Array<String>] Destination for extracted blocks.
+      # @param placeholder [String] Placeholder format string.
+      # @return [String] Documentation with fenced blocks replaced.
+      def extract_fenced_code_blocks(docstring, fenced_code_blocks, placeholder)
+        docstring.gsub(/^```[^\n]*\n.*?^```[ \t]*$/m) do |block|
+          format(placeholder, fenced_code_blocks.push(block).length - 1)
         end
+      end
 
-        markdown
+      # Restores fenced blocks after RDoc conversion.
+      #
+      # @param markdown [String] Converted Markdown text.
+      # @param fenced_code_blocks [Array<String>] Extracted fenced blocks.
+      # @param placeholder [String] Placeholder format string.
+      # @return [String] Markdown with fenced blocks restored.
+      def restore_fenced_code_blocks(markdown, fenced_code_blocks, placeholder)
+        fenced_code_blocks.each_with_index.reduce(markdown) do |text, (block, index)|
+          text.sub(format(placeholder, index), block)
+        end
       end
     end
   end

data/lib/yard/markdown/heading_helper.rb

@@ -4,22 +4,21 @@ module YARD
   module Markdown
     # Builds headings and legacy anchors for rendered object sections.
     module HeadingHelper
-      include ArefHelper
-
       # Returns the legacy YARD anchor for an object when one exists.
       #
       # @param object [YARD::CodeObjects::Base] Object being rendered.
       # @return [String, nil] Legacy anchor id, if supported.
-      def legacy_aref(object)
-        type = object.type
-
-        return "#{object.name}-constant" if type == :constant
-        return "#{object.name}-classvariable" if type == :classvariable
-        return nil unless object.respond_to?(:scope)
-
-        return "#{object.name}-class_method" if object.scope == :class
-
-        "#{object.name}-instance_method"
+      def self.legacy_aref(object)
+        name = object.name
+
+        case object.type
+        when :constant
+          "#{name}-constant"
+        when :classvariable
+          "#{name}-classvariable"
+        when :method
+          "#{name}-#{(object.scope == :class) ? "class" : "instance"}_method"
+        end
       end
 
       # Returns all anchor tags that should be attached to a heading.
@@ -27,7 +26,7 @@ module YARD
       # @param object [YARD::CodeObjects::Base] Object being rendered.
       # @return [Array<String>] HTML anchor tags for the object.
       def anchor_tags_for(object)
-        anchors = [aref(object), legacy_aref(object)].compact
+        anchors = [ArefHelper.aref(object), HeadingHelper.legacy_aref(object)].compact
         anchors.map { |id| anchor_tag(id) }
       end
 

data/lib/yard/markdown/link_normalization_helper.rb

@@ -10,12 +10,9 @@ module YARD
       # @param current_path [String] Output path for the current document.
       # @return [String] Normalized Markdown content with a trailing newline.
       def finalize_markdown(content, current_path)
-        output = content.instance_of?(Array) ? content.join("\n") : content
-        output = output.lines.map(&:rstrip).join("\n")
-        output = normalize_local_links(output, current_path)
-        output = normalize_malformed_local_links(output)
-        output = output.gsub(/\n{3,}/, "\n\n").strip
-        "#{output}\n"
+        LinkNormalizationHelper.finish_markdown(
+          normalize_local_links(LinkNormalizationHelper.normalize_lines(content), current_path)
+        )
       end
 
       # Rewrites local Markdown links relative to the current output path.
@@ -27,17 +24,7 @@ module YARD
         current_dir = Pathname.new(current_path).dirname
 
         markdown.gsub(%r{\[(.+?)\]\((?!https?://|mailto:|#)([^)\n]+)\)}) do
-          label = Regexp.last_match(1)
-          target = Regexp.last_match(2)
-          path = target.sub(/[?#].*\z/, "")
-          suffix = target[path.length..]
-          rewritten_path = resolve_local_link_target(path, current_dir)
-
-          if rewritten_path.nil?
-            "`#{label.tr("`", "")}`"
-          else
-            "[#{label}](#{rewritten_path}#{suffix})"
-          end
+          normalize_local_link(Regexp.last_match, current_dir)
         end
       end
 
@@ -46,28 +33,37 @@ module YARD
       # @param path [String] Link target path to resolve.
       # @param current_dir [Pathname] Directory for the current output file.
       # @return [YARD::CodeObjects::Base, nil] Matched registry object, if any.
-      def resolve_registry_object(path, current_dir)
-        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
-        candidates = [path]
-
-        if constant_reference_path?(cleaned)
-          current_parts = current_dir.to_s.split("/").reject { |part| part.empty? || part == "." }
-          target_parts = cleaned.split("/")
-
-          current_parts.length.downto(0) do |depth|
-            candidates << (current_parts.first(depth) + target_parts).join("::")
-          end
-        end
+      def self.resolve_registry_object(path, current_dir)
+        registry_candidates(path, current_dir)
+          .map { |candidate| Registry.at(candidate) }
+          .compact
+          .reject { |object| object.equal?(Registry.root) }
+          .first
+      end
 
-        candidates.each do |candidate|
-          obj = Registry.at(candidate)
-          next if obj.nil? || obj.equal?(Registry.root)
+      # Returns registry paths that may match a local target.
+      #
+      # @param path [String] Link target path to resolve.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [Array<String>] Candidate registry paths in lookup order.
+      def self.registry_candidates(path, current_dir)
+        cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
+        return [path] unless constant_reference_path?(cleaned)
 
-          return obj
-        end
+        namespaced_candidates(cleaned, current_dir)
+      end
 
-        nil
+      # Expands a constant target through each enclosing namespace.
+      #
+      # @param cleaned [String] Target without relative path prefixes.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [Array<String>] Namespaced registry candidates.
+      def self.namespaced_candidates(cleaned, current_dir)
+        current_parts = current_dir.to_s.split("/").reject { |part| part.empty? || part == "." }
+        target_parts = cleaned.split("/")
+        current_parts.length.downto(0).map { |depth| (current_parts.first(depth) + target_parts).join("::") }
       end
+      private_class_method :registry_candidates, :namespaced_candidates
 
       # Resolves a local link target to the final relative Markdown path.
       #
@@ -76,29 +72,15 @@ module YARD
       # @return [String, nil] Relative Markdown path, or nil when unresolved.
       def resolve_local_link_target(path, current_dir)
         normalized = path.sub(%r{\A/+}, "")
-
-        obj = resolve_registry_object(normalized, current_dir)
-        if obj
-          object_path = options.serializer.serialized_path(obj)
-          return relative_output_path(current_dir, object_path)
-        end
-
-        if normalized.match?(/\.html\z/i)
-          normalized = normalized.sub(/\.html\z/i, ".md")
-        elsif File.extname(normalized).empty?
-          return nil if unresolved_identifier_target?(normalized)
-
-          normalized = "#{normalized}.md" if normalized.include?("/")
-        end
-
-        relative_output_path(current_dir, normalized)
+        target = registry_path(normalized, current_dir) || copied_path(normalized) || LinkNormalizationHelper.markdown_path(normalized)
+        LinkNormalizationHelper.relative_output_path(current_dir, target) if target
       end
 
       # Returns whether a path looks like a constant reference.
       #
       # @param value [String] Link target to inspect.
       # @return [Boolean] True when the path resembles a constant name.
-      def constant_reference_path?(value)
+      def self.constant_reference_path?(value)
         parts = value.split(%r{::|/}).reject(&:empty?)
         return false if parts.empty?
 
@@ -109,11 +91,9 @@ module YARD
       #
       # @param path [String] Link target to inspect.
       # @return [Boolean] True when the target should be treated as unresolved.
-      def unresolved_identifier_target?(path)
+      def self.unresolved_identifier_target?(path)
         cleaned = path.sub(%r{\A(?:(?:\.\./)+|\./)}, "")
-        return true if cleaned.start_with?(":") || cleaned.match?(/\A\d/)
-
-        cleaned.match?(/\A[a-z_]\w*\z/)
+        File.extname(cleaned).empty? && !cleaned.include?("/")
       end
 
       # Computes a relative path from the current output directory.
@@ -121,7 +101,7 @@ module YARD
       # @param current_dir [Pathname] Directory for the current output file.
       # @param target_path [String, Pathname] Output path being linked to.
       # @return [String] Relative path suitable for a Markdown link.
-      def relative_output_path(current_dir, target_path)
+      def self.relative_output_path(current_dir, target_path)
         target = target_path.to_s
         return target if target.start_with?("../")
 
@@ -130,12 +110,70 @@ module YARD
         target
       end
 
-      # Replaces malformed local Markdown links with inline code.
+      # Converts supported content into normalized lines.
+      #
+      # @param content [String, Array<String>] Markdown content.
+      # @return [String] Joined content without trailing line whitespace.
+      def self.normalize_lines(content)
+        text = content.instance_of?(Array) ? content.join("\n") : content
+        text.lines.map(&:rstrip).join("\n")
+      end
+
+      # Compacts blank lines and adds the final newline.
+      #
+      # @param markdown [String] Normalized Markdown content.
+      # @return [String] Final Markdown content.
+      def self.finish_markdown(markdown)
+        "#{markdown.gsub(/\n{3,}/, "\n\n").strip}\n"
+      end
+
+      # Returns the Markdown output path for a non-registry target.
+      #
+      # @param path [String] Local link target.
+      # @return [String, nil] Markdown path, or nil for an unresolved identifier.
+      def self.markdown_path(path)
+        return path.sub(/\.html\z/i, ".md") if path.match?(/\.html\z/i)
+        return path unless File.extname(path).empty?
+        return if unresolved_identifier_target?(path)
+
+        "#{path}.md"
+      end
+
+      private
+
+      # Rewrites one matched local Markdown link.
+      #
+      # @param match [MatchData] Local link match.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [String] Rewritten link or code-formatted label.
+      def normalize_local_link(match, current_dir)
+        label, target = match.captures
+        path, separator, suffix = target.partition(/[?#]/)
+        rewritten_path = resolve_local_link_target(path, current_dir)
+        return "[#{label}](#{rewritten_path}#{separator}#{suffix})" if rewritten_path
+
+        "`#{label.tr("`", "")}`"
+      end
+
+      # Finds the serialized path for a registry object.
+      #
+      # @param path [String] Local link target.
+      # @param current_dir [Pathname] Directory for the current output file.
+      # @return [String, nil] Serialized object path, if resolved.
+      def registry_path(path, current_dir)
+        object = LinkNormalizationHelper.resolve_registry_object(path, current_dir)
+        return unless object
+
+        options.serializer.serialized_path(object)
+      end
+
+      # Finds a copied Markdown file by its normalized alias.
       #
-      # @param markdown [String] Markdown content to normalize.
-      # @return [String] Markdown with malformed local links replaced.
-      def normalize_malformed_local_links(markdown)
-        markdown.gsub(%r{\[([^\]]+)\]\((?!https?://|mailto:|#)(?:[^)\n]*['"][^)\n]*)\)}, '`\1`')
+      # @param path [String] Local link target.
+      # @return [String, nil] Copied file path, if registered.
+      def copied_path(path)
+        alias_path = Pathname.new(path.sub(/\.html\z/i, "")).cleanpath.to_s
+        options.copied_file_aliases[alias_path]
       end
     end
   end

data/lib/yard/markdown/metadata_section_helper.rb

@@ -9,21 +9,9 @@ module YARD
       # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
       # @return [String] Markdown table containing the object's metadata.
       def object_metadata(object)
-        rows = []
-
-        if object.instance_of?(CodeObjects::ClassObject)
-          rows << ["Inherits", metadata_reference(object.superclass)]
-        end
-
-        [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, label|
-          mixins = run_verifier(object.mixins(scope)).sort_by { |item| item.path }
-          next if mixins.empty?
-
-          rows << [label, mixins.map { |mixin| metadata_reference(mixin) }.join(", ")]
-        end
-
-        files = object.files.map(&:first).uniq
-        rows << ["Defined in", files.map { |file| metadata_table_cell(file) }.join(", ")] unless files.empty?
+        superclass = object.superclass if object.instance_of?(CodeObjects::ClassObject)
+        rows = (superclass ? [["Inherits", metadata_reference(superclass)]] : []) +
+          mixin_rows(object) + MetadataSectionHelper.file_rows(object)
 
         return "" if rows.empty?
 
@@ -35,20 +23,57 @@ module YARD
       # @param target [YARD::CodeObjects::NamespaceObject, YARD::CodeObjects::Proxy] Referenced namespace.
       # @return [String] Markdown link or plain table-cell text.
       def metadata_reference(target)
-        label = metadata_table_cell(target.path)
-        return label unless target.is_a?(CodeObjects::Base) && run_verifier([target]).any?
+        path = target.path
+        label = MetadataSectionHelper.metadata_table_cell(path)
+        return label unless target.is_a?(CodeObjects::NamespaceObject) && run_verifier([target]).any?
 
-        "[#{label}](#{target.path})"
+        "[#{label}](#{path})"
       end
 
       # Escapes text for a Markdown table cell.
       #
       # @param value [String] Metadata text.
       # @return [String] GFM table-safe Markdown text.
-      def metadata_table_cell(value)
+      def self.metadata_table_cell(value)
         value.gsub(/[[:blank:]]*\R[[:blank:]]*/, " ")
           .gsub(/[\\|]/) { |character| "\\#{character}" }
       end
+
+      # Builds the source-file metadata rows.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Namespace being rendered.
+      # @return [Array<Array>] Source-file rows.
+      def self.file_rows(object)
+        files = object.files.map(&:first).uniq
+        return [] if files.empty?
+
+        [["Defined in", files.map { |file| metadata_table_cell(file) }.join(", ")]]
+      end
+
+      private
+
+      # Builds class and instance mixin rows.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Namespace being rendered.
+      # @return [Array<Array>] Visible mixin rows.
+      def mixin_rows(object)
+        [[:class, "Extended by"], [:instance, "Includes"]]
+          .map { |scope, label| mixin_row(object, scope, label) }
+          .compact
+      end
+
+      # Builds one scoped mixin row.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Namespace being rendered.
+      # @param scope [Symbol] Mixin scope.
+      # @param label [String] Metadata row label.
+      # @return [Array, nil] Mixin row, if visible mixins exist.
+      def mixin_row(object, scope, label)
+        mixins = run_verifier(object.mixins(scope)).sort_by(&:path)
+        return if mixins.empty?
+
+        [label, mixins.map { |mixin| metadata_reference(mixin) }.join(", ")]
+      end
     end
   end
 end

data/lib/yard/markdown/method_presentation_helper.rb

@@ -8,7 +8,7 @@ module YARD
       #
       # @param method_object [YARD::CodeObjects::MethodObject] Method being rendered.
       # @return [String] Method heading text.
-      def formatted_method_heading(method_object)
+      def self.formatted_method_heading(method_object)
         name = method_object.name
         signature = method_signature(method_object)
         signature = " #{signature}" if name.end_with?("]")
@@ -19,11 +19,9 @@ module YARD
       #
       # @param method_object [YARD::CodeObjects::MethodObject] Method being rendered.
       # @return [String] Parenthesized method signature.
-      def method_signature(method_object)
-        return "()" if method_object.parameters.nil?
-
-        rendered = method_object.parameters.map do |name, default|
-          (default.nil? || default.empty?) ? name : "#{name} = #{default}"
+      def self.method_signature(method_object)
+        rendered = Array(method_object.parameters).map do |name, default|
+          default.to_s.empty? ? name : "#{name} = #{default}"
         end
 
         "(#{rendered.join(", ")})"
@@ -33,7 +31,7 @@ module YARD
       #
       # @param attribute [YARD::CodeObjects::MethodObject] Attribute reader or writer.
       # @return [String] Access mode marker such as `R`, `W`, or `RW`.
-      def attribute_access(attribute)
+      def self.attribute_access(attribute)
         read, write = attribute.attr_info.fetch_values(:read, :write)
         return "RW" if read && write
         return "R" if read

data/lib/yard/markdown/object_listing_helper.rb

@@ -8,7 +8,7 @@ module YARD
       #
       # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
       # @return [Array<YARD::CodeObjects::Base>] Constants and class variables.
-      def constant_listing(object)
+      def self.constant_listing(object)
         constants = object.constants(included: false, inherited: false)
         constants + object.cvars
       end
@@ -19,7 +19,7 @@ module YARD
       # @return [Array<YARD::CodeObjects::MethodObject>] Sorted public methods.
       def public_method_list(object)
         prune_method_listing(object.meths(inherited: false, visibility: :public))
-          .reject { |item| hidden_object?(item) }
+          .reject { |item| ObjectListingHelper.hidden_object?(item) }
           .sort_by { |method_object| method_object.name }
       end
 
@@ -44,44 +44,50 @@ module YARD
       # @param object [YARD::CodeObjects::NamespaceObject] Object being rendered.
       # @return [Array<YARD::CodeObjects::MethodObject>] Sorted attribute methods.
       def attr_listing(object)
-        attrs = []
-
-        object.inheritance_tree(true).each do |superclass|
-          next if !options.embed_mixins.empty? && !options.embed_mixins_match?(superclass)
-
-          %i[class instance].each do |scope|
-            superclass.attributes.fetch(scope).each do |_name, rw|
-              attr = prune_method_listing([rw.fetch(:read), rw.fetch(:write)].compact, false).first
-              attrs << attr if attr
-            end
-          end
-
-          break if options.embed_mixins.empty?
-        end
-
-        sort_listing(attrs)
+        superclasses = attribute_superclasses(object)
+        attributes = superclasses.flat_map { |superclass| attributes_for(superclass) }
+        ObjectListingHelper.sort_attributes(attributes)
       end
 
-      # Sorts a listing by scope and case-insensitive name.
+      # Sorts attributes by scope and case-insensitive name.
       #
-      # @param list [Array<YARD::CodeObjects::Base>] Objects to sort.
-      # @return [Array<YARD::CodeObjects::Base>] Sorted objects.
-      def sort_listing(list)
-        list.sort do |left, right|
-          scope_comparison = left.scope <=> right.scope
-          next scope_comparison unless scope_comparison.zero?
-
-          left.name.to_s.casecmp(right.name.to_s)
-        end
+      # @param attributes [Array<YARD::CodeObjects::MethodObject>] Attribute methods collected from eligible ancestors.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Sorted attributes.
+      def self.sort_attributes(attributes)
+        attributes.sort { |left, right| (left.scope <=> right.scope).nonzero? || left.name.to_s.casecmp(right.name.to_s) }
       end
 
       # Returns whether an object is explicitly hidden with `:nodoc:`.
       #
       # @param object [YARD::CodeObjects::Base] Listed object whose docstring may start with `:nodoc:`.
       # @return [Boolean] True when the object should be hidden.
-      def hidden_object?(object)
+      def self.hidden_object?(object)
         object.docstring.start_with?(":nodoc:")
       end
+
+      private
+
+      # Selects ancestors whose attributes should be embedded.
+      #
+      # @param object [YARD::CodeObjects::NamespaceObject] Namespace being rendered.
+      # @return [Array<YARD::CodeObjects::Base>] Eligible ancestors.
+      def attribute_superclasses(object)
+        superclasses = object.inheritance_tree(true)
+        return superclasses.first(1) if options.embed_mixins.empty?
+
+        superclasses.select { |superclass| options.embed_mixins_match?(superclass) }
+      end
+
+      # Collects visible attributes from one ancestor.
+      #
+      # @param superclass [YARD::CodeObjects::Base] Ancestor containing attributes.
+      # @return [Array<YARD::CodeObjects::MethodObject>] Visible attributes.
+      def attributes_for(superclass)
+        superclass.attributes.values.flat_map(&:values).map { |read_write|
+          read, write = read_write.fetch_values(:read, :write)
+          prune_method_listing([read, write].compact, false).first
+        }.compact
+      end
     end
   end
 end

data/lib/yard/markdown/section_assembly_helper.rb

@@ -8,7 +8,7 @@ module YARD
       #
       # @param content [Object] Section content to render.
       # @return [String] Section content followed by blank-line spacing.
-      def render_section_content(content)
+      def self.render_section_content(content)
         text = content.to_s.strip
         return "" if text.empty?
 
@@ -20,27 +20,20 @@ module YARD
       # @param items [Array<#group>] Renderable objects that expose a YARD group name.
       # @param group_order [Array<String>, nil] Preferred ordering for named groups.
       # @return [Array<Array>] Ordered pairs of group names and grouped items.
-      def grouped_items(items, group_order)
+      def self.grouped_items(items, group_order)
         groups = items.group_by(&:group)
-        names = groups.keys
-        order = Array(group_order)
-        ordered_names = (order & names) + (names.compact - order).sort + ([nil] & names)
-
-        ordered_names.map { |name| [name, groups.fetch(name)] }
+        ordered_group_names(groups.keys, Array(group_order)).map { |name| [name, groups.fetch(name)] }
       end
 
-      # Appends non-empty content to a mutable list of lines.
+      # Orders known group names by configured, alphabetical, and default order.
       #
-      # @param lines [Array<String>] Destination line buffer.
-      # @param content [String] Rendered Markdown block to split into lines.
-      # @param separated [Boolean] Whether to insert a blank separator line first.
-      # @return [void]
-      def append_lines(lines, content, separated: true)
-        return if content.lstrip.empty?
-
-        lines << "" if separated && !lines.empty? && !lines.last.empty?
-        lines.concat(content.split("\n"))
+      # @param names [Array<String, nil>] Known group names.
+      # @param order [Array<String>] Preferred named-group order.
+      # @return [Array<String, nil>] Ordered group names.
+      def self.ordered_group_names(names, order)
+        (order & names) + (names.compact - order).sort + ([nil] & names)
       end
+      private_class_method :ordered_group_names
     end
   end
 end

data/lib/yard/markdown/tag_formatting_helper.rb

@@ -8,43 +8,31 @@ module YARD
       #
       # @param object [YARD::CodeObjects::Base] Object whose tags are being rendered.
       # @return [String] Markdown representation of the object's tags.
-      def render_tags(object)
+      def self.render_tags(object)
         example_tags, regular_tags = object.tags.partition { |tag| tag.tag_name == "example" }
-        lines = regular_tags.map { |tag| "- #{format_tag(tag)}" }
-
-        example_tags.each do |tag|
-          lines << nil unless lines.empty?
-          title = tag.name.to_s.rstrip.empty? ? "**@example**" : "**@example #{tag.name}**"
-          lines << title
-          lines << "```ruby"
-          lines << tag.text.to_s.rstrip
-          lines << "```"
+        regular = regular_tags.map { |tag| "- #{format_tag(tag)}" }.join("\n")
+        examples = example_tags.map do |tag|
+          name = tag.name.to_s.rstrip
+          title = name.empty? ? "**@example**" : "**@example #{name}**"
+          [title, "```ruby", tag.text.to_s.rstrip, "```"].join("\n")
         end
-
-        lines.join("\n")
+        [regular, examples].reject(&:empty?).join("\n\n")
       end
 
       # Formats a non-example YARD tag as a Markdown list item body.
       #
       # @param tag [YARD::Tags::Tag] Non-example tag being converted into list item text.
       # @return [String] Markdown representation of the tag.
-      def format_tag(tag)
-        parts = ["**@#{tag.tag_name}**"]
-        parts << "`#{tag.name}`" unless tag.name.to_s.lstrip.empty?
-
-        cleaned_types = normalized_tag_types(tag.types)
-        parts << "[#{cleaned_types.join(", ")}]" unless cleaned_types.empty?
-        parts << tag.text.strip unless tag.text.to_s.lstrip.empty?
-
-        parts.join(" ")
-      end
-
-      # Normalizes tag type declarations into printable strings.
-      #
-      # @param types [Array<Object>, nil] Raw tag types from YARD.
-      # @return [Array<String>] Cleaned type strings.
-      def normalized_tag_types(types)
-        Array(types).map(&:to_s).map(&:strip).reject(&:empty?)
+      def self.format_tag(tag)
+        name = tag.name.to_s
+        text = tag.text.to_s
+        types = Array(tag.types).map { |type| type.to_s.strip }.reject(&:empty?)
+        [
+          "**@#{tag.tag_name}**",
+          ("`#{name}`" unless name.lstrip.empty?),
+          ("[#{types.join(", ")}]" unless types.empty?),
+          (text.strip unless text.lstrip.empty?)
+        ].compact.join(" ")
       end
     end
   end

data/lib/yard/markdown/yardoc_extension.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Discovers Markdown pages before YARD generates documentation.
+    module YardocExtension
+      private
+
+      # Adds Markdown pages to the files rendered by the Markdown template.
+      #
+      # @param checksums [Hash, nil] Previously generated file checksums.
+      # @return [void]
+      def run_generate(checksums)
+        add_extra_files(markdown_files) if options.format == :markdown
+
+        super
+      end
+
+      # Returns project Markdown files that YARD has not already discovered.
+      #
+      # @return [Array<String>] Markdown file paths to add.
+      def markdown_files
+        Dir.glob("**/*").grep(FILE_PATTERN)
+          .reject { |file| File.basename(file).start_with?("_") }
+          .reject { |file| excluded_file?(file) }
+          .reject { |file| output_file?(file) }
+          .reject { |file| existing_file?(file) }
+      end
+
+      # Returns whether a file matches a configured exclusion.
+      #
+      # @param file [String] Candidate file path.
+      # @return [Boolean] True when excluded.
+      def excluded_file?(file)
+        excluded.any? { |path| Regexp.new(path, Regexp::IGNORECASE).match?(file) }
+      end
+
+      # Returns whether a file is inside the output directory.
+      #
+      # @param file [String] Candidate file path.
+      # @return [Boolean] True when generated output would contain the file.
+      def output_file?(file)
+        output = File.expand_path(options.serializer.basepath)
+        File.expand_path(file).start_with?("#{output}/")
+      end
+
+      # Returns whether YARD has already discovered a file.
+      #
+      # @param file [String] Candidate file path.
+      # @return [Boolean] True when the file already exists in YARD options.
+      def existing_file?(file)
+        expanded_file = File.expand_path(file)
+        options.files.any? { |existing| File.expand_path(existing.filename) == expanded_file }
+      end
+    end
+  end
+end

data/lib/yard/markdown.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module YARD
+  module Markdown
+    # Matches supported Markdown file extensions.
+    FILE_PATTERN = /\.(?:md|markdown)\z/i
+  end
+end

data/lib/yard-markdown.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yard"
+require_relative "yard/markdown"
 require_relative "yard/markdown/aref_helper"
 require_relative "yard/markdown/collection_rendering_helper"
 require_relative "yard/markdown/documentation_helper"
@@ -11,10 +12,7 @@ require_relative "yard/markdown/method_presentation_helper"
 require_relative "yard/markdown/object_listing_helper"
 require_relative "yard/markdown/section_assembly_helper"
 require_relative "yard/markdown/tag_formatting_helper"
-
-module YARD
-  module Markdown
-  end
-end
+require_relative "yard/markdown/yardoc_extension"
 
 YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + "/../templates"
+YARD::CLI::Yardoc.prepend(YARD::Markdown::YardocExtension)

data/templates/default/fulldoc/markdown/setup.rb

@@ -3,20 +3,26 @@
 require "csv"
 
 include YARD::Markdown::ObjectListingHelper,
-  YARD::Markdown::ArefHelper,
   YARD::Templates::Helpers::ModuleHelper
 
 # Prepares the markdown serializer and renders each object page.
 #
 # @return [void]
 def init
-  options.objects = objects = run_verifier(options.objects).reject { |item| item.name == :root }
+  objects = run_verifier(options.objects).reject { |item| item.name == :root }
+  files = Array(options.files).select { |file| file.filename.match?(YARD::Markdown::FILE_PATTERN) }
+  options.copied_file_aliases = files.to_h do |file|
+    path = Pathname.new(file.filename).cleanpath.to_s
+    [path.sub(YARD::Markdown::FILE_PATTERN, ""), path]
+  end
 
   options.delete(:objects)
   options.delete(:files)
 
   options.serializer.extension = "md"
 
+  files.each { |file| options.serializer.serialize(file.filename, File.binread(file.filename)) }
+
   objects.each do |object|
     Templates::Engine.with_serializer(object, options.serializer) { serialize(object) }
   rescue => e
@@ -25,7 +31,7 @@ def init
     log.backtrace(e)
   end
 
-  serialize_index(objects)
+  serialize_index(objects, files)
 end
 
 # Renders the markdown template for a single namespace object.
@@ -39,16 +45,17 @@ end
 # Writes the CSV search index for all rendered objects.
 #
 # @param objects [Array<YARD::CodeObjects::NamespaceObject>] Verified objects included in the generated documentation.
+# @param files [Array<YARD::CodeObjects::ExtraFileObject>] Markdown files included in the generated documentation.
 # @return [void]
-def serialize_index(objects)
+def serialize_index(objects, files)
   filepath = "#{options.serializer.basepath}/index.csv"
 
   CSV.open(filepath, "wb") do |csv|
     csv << %w[name type path]
 
-    objects.each do |object|
-      next if object.name == :root
+    files.each { |file| csv << [file.filename, "File", file.filename] }
 
+    objects.each do |object|
       if object.type == :class
         csv << [object.path, "Class", options.serializer.serialized_path(object)]
       elsif object.type == :module
@@ -56,7 +63,7 @@ def serialize_index(objects)
       end
 
       [
-        ["Constant", constant_listing(object)],
+        ["Constant", YARD::Markdown::ObjectListingHelper.constant_listing(object)],
         ["Method", public_instance_methods(object)],
         ["Method", public_class_methods(object)],
         ["Attribute", attr_listing(object)]
@@ -65,7 +72,7 @@ def serialize_index(objects)
           csv << [
             "#{object.path}.#{item.name(false)}",
             type,
-            options.serializer.serialized_path(object) + "#" + aref(item)
+            options.serializer.serialized_path(object) + "#" + YARD::Markdown::ArefHelper.aref(item)
           ]
         end
       end

data/templates/default/module/markdown/setup.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-include YARD::Markdown::TagFormattingHelper,
-  YARD::Markdown::SectionAssemblyHelper,
-  YARD::Markdown::MetadataSectionHelper,
+include YARD::Markdown::MetadataSectionHelper,
   YARD::Markdown::ObjectListingHelper,
-  YARD::Markdown::MethodPresentationHelper,
   YARD::Markdown::LinkNormalizationHelper,
   YARD::Markdown::HeadingHelper,
   YARD::Markdown::DocumentationHelper,
@@ -45,48 +42,49 @@ end
 #
 # @return [String] Markdown heading section.
 def header
-  render_section_content(heading_with_anchors("# #{object.type.to_s.capitalize} #{object.path}", object))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(heading_with_anchors("# #{object.type.to_s.capitalize} #{object.path}", object))
 end
 
 # Renders metadata for the current object.
 #
 # @return [String] Markdown metadata section.
 def metadata
-  render_section_content(object_metadata(object))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(object_metadata(object))
 end
 
 # Renders the object's docstring as markdown.
 #
 # @return [String] Markdown docstring section.
 def docstring_section
-  render_section_content(rdoc_to_md(object.docstring))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(rdoc_to_md(object.docstring))
 end
 
 # Renders the object's YARD tags.
 #
 # @return [String] Markdown tags section.
 def tags_section
-  render_section_content(render_tags(object))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(YARD::Markdown::TagFormattingHelper.render_tags(object))
 end
 
 # Renders the constants section when visible constants are present.
 #
 # @return [String] Markdown constants section, or an empty string.
 def constants_section
-  constants = constant_listing(object).reject { |item| hidden_object?(item) }
+  constants = YARD::Markdown::ObjectListingHelper.constant_listing(object)
+    .reject { |item| YARD::Markdown::ObjectListingHelper.hidden_object?(item) }
   return "" unless constants.any?
 
-  render_section_content(render_constants(constants, Array(object.groups)))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(render_constants(constants, Array(object.groups)))
 end
 
 # Renders the attributes section when visible attributes are present.
 #
 # @return [String] Markdown attributes section, or an empty string.
 def attributes_section
-  attrs = attr_listing(object).reject { |item| hidden_object?(item) }
+  attrs = attr_listing(object).reject { |item| YARD::Markdown::ObjectListingHelper.hidden_object?(item) }
   return "" unless attrs.any?
 
-  render_section_content(render_attributes(attrs, Array(object.groups)))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(render_attributes(attrs, Array(object.groups)))
 end
 
 # Renders the public class methods section when methods are present.
@@ -96,7 +94,7 @@ def public_class_methods_section
   methods = public_class_methods(object)
   return "" unless methods.any?
 
-  render_section_content(render_methods("Public Class Methods", methods, Array(object.groups)))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(render_methods("Public Class Methods", methods, Array(object.groups)))
 end
 
 # Renders the public instance methods section when methods are present.
@@ -106,5 +104,5 @@ def public_instance_methods_section
   methods = public_instance_methods(object)
   return "" unless methods.any?
 
-  render_section_content(render_methods("Public Instance Methods", methods, Array(object.groups)))
+  YARD::Markdown::SectionAssemblyHelper.render_section_content(render_methods("Public Instance Methods", methods, Array(object.groups)))
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-markdown
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Stanislav (Stas) Katkov
@@ -62,6 +62,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/yard-markdown.rb
+- lib/yard/markdown.rb
 - lib/yard/markdown/aref_helper.rb
 - lib/yard/markdown/collection_rendering_helper.rb
 - lib/yard/markdown/documentation_helper.rb
@@ -72,6 +73,7 @@ files:
 - lib/yard/markdown/object_listing_helper.rb
 - lib/yard/markdown/section_assembly_helper.rb
 - lib/yard/markdown/tag_formatting_helper.rb
+- lib/yard/markdown/yardoc_extension.rb
 - templates/default/fulldoc/markdown/setup.rb
 - templates/default/module/markdown/setup.rb
 homepage: https://poshtui.com