yard-markdown-relative-links 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbcb5b063125d5b23b85d928be3f180acc9c225504b93cf2ed75eb536e5e3971
+  data.tar.gz: fe4b93bcd506fae09bb4975aa0313729e1c64654b3f599e4da49e061d6264674
+SHA512:
+  metadata.gz: 2e403985e27ffc84edc382582b47530428cca504b38668a1410d7777d6c04b4be42482321a72af1ab174473d2f44a2cb91433b909b8aa0fa1923bb26d3a6ab0e
+  data.tar.gz: 13ad0ea218d206df70ca047eb183212e6c627587aacb63da22861a211034aff20f61411283329e9619208ae387cd371ab0ba781fe2e2b8565bf4322371b365f2

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-03
+
+### Changed
+
+- Replaced `Nokogiri` with a stdlib-only anchor rewriter for link conversion
+- Refactored file lookup caching to rebuild indexes when YARD file lists change
+
+### Added
+
+- Test coverage for uppercase/single-quoted anchors and malformed HTML fragments
+
+## [0.1.0] - 2026-03-03
+
+### Added
+
+- Initial release
+- Convert relative Markdown links to YARD file references
+- Support for files in subdirectories by resolving links relative to the current file's directory
+- Preserve anchor/fragment links (e.g., `file.md#section`)
+- Basename fallback matching when there's exactly one file with the matching name

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Daniel Harrington
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# yard-markdown-relative-links
+
+[![CI](https://github.com/rubiii/yard-markdown-relative-links/actions/workflows/ci.yml/badge.svg)](https://github.com/rubiii/yard-markdown-relative-links/actions/workflows/ci.yml)
+
+A YARD plugin to convert relative links between Markdown files.
+
+GitHub and YARD render Markdown files differently. In particular, relative links in Markdown files that work in GitHub don't work in YARD. For example, if you have `[hello](FOO.md)` in your README, YARD renders it as `<a href="FOO.md">hello</a>`, creating a broken link in your docs.
+
+With this plugin enabled, you'll get `<a href="file.FOO.html">hello</a>` instead, which correctly links through to the rendered HTML file.
+
+## Features
+
+- Converts relative Markdown links to YARD file references
+- **Supports files in subdirectories** — links from `docs/index.md` to `getting-started.md` correctly resolve to `docs/getting-started.md`
+- Preserves anchor/fragment links (e.g., `file.md#section`)
+- Falls back to basename matching for simple cases
+- No `Nokogiri` runtime dependency (stdlib-only link rewriting)
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'yard-markdown-relative-links'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install yard-markdown-relative-links
+```
+
+## Usage
+
+Add this line to your application's `.yardopts`:
+
+```
+--plugin relative_markdown_links
+```
+
+You'll also need to make sure your Markdown files are processed by YARD. To include all Markdown files in your project, add the following lines to the end of your application's `.yardopts`:
+
+```
+-
+**/*.md
+```
+
+### Example `.yardopts`
+
+```
+--markup markdown
+--plugin relative_markdown_links
+--readme README.md
+-
+docs/*.md
+lib/**/*.rb
+```
+
+## How It Works
+
+When YARD processes your Markdown files, this plugin intercepts the HTML output and converts relative links to YARD's `{file:}` syntax.
+
+The plugin resolves links in three ways:
+
+1. **Exact match** — If the link path exactly matches a file in YARD's file list (e.g., `docs/index.md`), it's used directly.
+
+2. **Relative to current file** — If processing `docs/index.md` and it contains a link to `getting-started.md`, the plugin resolves this relative to the current file's directory, finding `docs/getting-started.md`.
+
+3. **Basename fallback** — If there's exactly one file with the matching basename, it's used (e.g., `getting-started.md` matches `docs/getting-started.md` if that's the only file with that name).
+
+## Background
+
+### Origins
+
+This gem is a replacement for the original [`yard-relative_markdown_links`](https://github.com/haines/yard-relative_markdown_links) gem created by Andrew Haines. The original gem was archived in February 2026.
+
+The original gem solved an important problem: relative links between Markdown files that work on GitHub don't work in YARD-generated documentation. However, it had a limitation — it only matched links against exact file paths in YARD's file list, which meant links between files in subdirectories didn't work properly.
+
+For example, if you had documentation in a `docs/` folder:
+
+```
+docs/
+├── index.md        # contains [Getting Started](getting-started.md)
+└── getting-started.md
+```
+
+The link in `index.md` would work on GitHub but not in YARD, because the original gem looked for `getting-started.md` in the file list, but YARD registered it as `docs/getting-started.md`.
+
+### Comparison with the Original Gem
+
+| Feature | Original | This Gem |
+|---------|----------|----------|
+| Convert exact path matches | ✅ | ✅ |
+| Preserve fragment/anchors (`#section`) | ✅ | ✅ |
+| Skip absolute URLs | ✅ | ✅ |
+| RDoc filename mapping | ✅ | ✅ |
+| **Subdirectory support** | ❌ | ✅ |
+| **Parent directory (`..`) resolution** | ❌ | ✅ |
+| **Basename fallback matching** | ❌ | ✅ |
+| **Malformed URI handling** | ❌ | ✅ |
+
+### Key Improvements
+
+1. **Subdirectory support** — When processing `docs/index.md`, a link to `getting-started.md` is resolved relative to the current file's directory, correctly finding `docs/getting-started.md`.
+
+2. **Parent directory resolution** — Links like `../other-file.md` are normalized and resolved correctly.
+
+3. **Basename fallback** — If there's exactly one file with a matching basename, it's used even without the full path.
+
+4. **Error handling** — Malformed URIs are gracefully skipped instead of raising exceptions.
+
+## Development
+
+Run tests:
+
+```sh
+bundle exec rake test
+```
+
+Run linting:
+
+```sh
+bundle exec rake lint
+```
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/lib/yard/relative_markdown_links/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module YARD
+  module RelativeMarkdownLinks
+    VERSION = '0.2.0'
+  end
+end

data/lib/yard/relative_markdown_links.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative 'relative_markdown_links/version'
+
+module YARD
+  # A YARD plugin to convert relative links between Markdown files.
+  #
+  # GitHub and YARD render Markdown files differently. In particular, relative
+  # links in Markdown files that work in GitHub don't work in YARD. For example,
+  # if you have `[hello](docs/FOO.md)` in your README, YARD renders it as
+  # `<a href="docs/FOO.md">hello</a>`, creating a broken link in your docs.
+  #
+  # With this plugin enabled, you'll get `<a href="file.FOO.html">hello</a>`
+  # instead, which correctly links through to the rendered HTML file.
+  #
+  # This plugin also properly handles files in subdirectories. For example,
+  # if `docs/index.md` links to `getting-started.md`, the plugin resolves
+  # the link relative to the current file's directory, finding
+  # `docs/getting-started.md` in YARD's file list.
+  module RelativeMarkdownLinks
+    ANCHOR_TAG_PATTERN = %r{<a\b(?<attributes>[^>]*)>(?<content>.*?)</a>}im
+    HREF_ATTRIBUTE_PATTERN = /
+      \bhref
+      \s*=\s*
+      (?:
+        "(?<double>[^"]*)"
+        |
+        '(?<single>[^']*)'
+        |
+        (?<bare>[^\s"'=<>`]+)
+      )
+    /imx
+    RDOC_FILENAME_PATTERN = %r{\A(?<dirname>(?:[^/#]*/)*+)(?<basename>[^/#]+)\.(?<ext>rb|rdoc|md)\z}i
+
+    # Resolves relative links from Markdown files.
+    #
+    # @param text [String] the HTML fragment in which to resolve links
+    # @return [String] HTML with relative links to extra files converted to `{file:}` links
+    def resolve_links(text)
+      return super unless options.files
+
+      super(rewrite_anchor_links(text))
+    end
+
+    private
+
+    # Replace supported HTML anchors with YARD {file:} references when they resolve to known files.
+    #
+    # @param text [String] HTML fragment to rewrite
+    # @return [String]
+    def rewrite_anchor_links(text)
+      text.gsub(ANCHOR_TAG_PATTERN) do |anchor_tag|
+        attributes = Regexp.last_match[:attributes]
+        content = Regexp.last_match[:content]
+        href = extract_href(attributes)
+        file_ref = href && resolve_href(href)
+
+        file_ref ? "{file:#{file_ref} #{content}}" : anchor_tag
+      end
+    end
+
+    # Extract the href attribute value from an <a ...> attribute string.
+    #
+    # @param attributes [String]
+    # @return [String, nil]
+    def extract_href(attributes)
+      match = HREF_ATTRIBUTE_PATTERN.match(attributes)
+      return nil unless match
+
+      match[:double] || match[:single] || match[:bare]
+    end
+
+    # Resolve a raw href string into a YARD file reference target.
+    #
+    # @param raw_href [String]
+    # @return [String, nil]
+    def resolve_href(raw_href)
+      href = URI(raw_href)
+      return nil unless href.relative?
+      return nil if href.query
+
+      path = href.path
+      return nil if path.nil? || path.empty?
+
+      resolved_path = resolve_file_path(path)
+      return nil unless resolved_path
+
+      href.fragment ? "#{resolved_path}##{href.fragment}" : resolved_path
+    rescue URI::InvalidURIError
+      # Skip malformed URIs
+      nil
+    end
+
+    # Resolve a relative file path to a known file in the YARD file list.
+    #
+    # @param path [String] the relative path from the link
+    # @return [String, nil] the resolved path if found, nil otherwise
+    def resolve_file_path(path)
+      indexes = file_indexes
+
+      # First, try exact match (works for root-level files like docs/index.md from README)
+      return path if indexes[:filenames].include?(path)
+
+      # Try RDoc-style filename mapping (e.g., foo_bar_md.html -> foo_bar.md)
+      rdoc_resolved = indexes[:rdoc_filenames][path]
+      return rdoc_resolved if rdoc_resolved
+
+      # Try RDoc-style basename-only matching
+      rdoc_basename_resolved = resolve_rdoc_by_basename(path, indexes[:rdoc_basename_to_paths])
+      return rdoc_basename_resolved if rdoc_basename_resolved
+
+      # Try resolving relative to current file's directory
+      resolved = resolve_relative_to_current_file(path, indexes[:filenames])
+      return resolved if resolved
+
+      # Fallback: try to find by basename alone (for simple cases)
+      resolve_by_basename(path, indexes[:basename_to_paths])
+    end
+
+    # Build and memoize lookup structures for the current options.files list.
+    #
+    # @return [Hash]
+    def file_indexes
+      filenames = options.files.map(&:filename)
+      return @file_indexes if @file_indexes && @file_indexes_filenames == filenames
+
+      @file_indexes_filenames = filenames
+      @file_indexes = {
+        filenames: filenames.to_set,
+        basename_to_paths: build_basename_mapping(filenames),
+        rdoc_filenames: build_rdoc_filename_mapping(filenames),
+        rdoc_basename_to_paths: build_rdoc_basename_mapping(filenames)
+      }
+    end
+
+    # Resolve a path relative to the current file being processed.
+    #
+    # @param path [String] the relative path from the link
+    # @param filenames [Set<String>] known filenames
+    # @return [String, nil] the resolved path if found, nil otherwise
+    def resolve_relative_to_current_file(path, filenames)
+      current_dir = current_file_directory
+      return nil unless current_dir
+
+      resolved = File.join(current_dir, path)
+      resolved = normalize_path(resolved)
+      resolved if filenames.include?(resolved)
+    end
+
+    # Resolve a path by matching its basename against known files.
+    #
+    # @param path [String] the relative path from the link
+    # @param basename_to_paths [Hash{String => Array<String>}]
+    # @return [String, nil] the resolved path if exactly one match, nil otherwise
+    def resolve_by_basename(path, basename_to_paths)
+      basename = File.basename(path)
+      candidates = basename_to_paths[basename]
+      candidates.first if candidates&.size == 1
+    end
+
+    # Get the directory of the current file being processed.
+    #
+    # @return [String, nil] the directory path, or nil if not available
+    def current_file_directory
+      # Try @file first (set in layout template)
+      return File.dirname(@file.filename) if defined?(@file) && @file.respond_to?(:filename)
+
+      # Try options.file (set during serialization)
+      return File.dirname(options.file.filename) if options.respond_to?(:file) && options.file.respond_to?(:filename)
+
+      nil
+    end
+
+    # Build a mapping from basename to full paths for fallback resolution.
+    #
+    # @param filenames [Array<String>] known filenames
+    # @return [Hash{String => Array<String>}] mapping of basenames to full paths
+    def build_basename_mapping(filenames)
+      mapping = Hash.new { |h, k| h[k] = [] }
+      filenames.each do |filename|
+        mapping[File.basename(filename)] << filename
+      end
+      mapping
+    end
+
+    # Build a mapping from RDoc-style HTML filenames to original filenames.
+    #
+    # RDoc generates filenames like `foo_bar_md.html` for `foo_bar.md`.
+    # This mapping allows resolving such links back to the original files.
+    #
+    # @param filenames [Array<String>] known filenames
+    # @return [Hash{String => String}] mapping of RDoc HTML names to original filenames
+    # @see https://github.com/ruby/rdoc/blob/0e060c69f51ec4a877e5cde69b31d47eaeb2a2b9/lib/rdoc/markup/to_html.rb#L364-L366
+    def build_rdoc_filename_mapping(filenames)
+      filenames.filter_map do |filename|
+        match = RDOC_FILENAME_PATTERN.match(filename)
+        next unless match
+
+        rdoc_name = "#{match[:dirname]}#{match[:basename].tr('.', '_')}_#{match[:ext]}.html"
+        [rdoc_name, filename]
+      end.to_h
+    end
+
+    # Build a mapping from RDoc-style basenames to original filenames.
+    #
+    # @param filenames [Array<String>] known filenames
+    # @return [Hash{String => Array<String>}] mapping of RDoc basenames to original filenames
+    def build_rdoc_basename_mapping(filenames)
+      mapping = Hash.new { |h, k| h[k] = [] }
+      filenames.each do |filename|
+        match = RDOC_FILENAME_PATTERN.match(filename)
+        next unless match
+
+        rdoc_basename = "#{match[:basename].tr('.', '_')}_#{match[:ext]}.html"
+        mapping[rdoc_basename] << filename
+      end
+      mapping
+    end
+
+    # Resolve RDoc-style filename by basename alone.
+    #
+    # @param path [String] the RDoc-style HTML filename (e.g., getting-started_md.html)
+    # @param rdoc_basename_to_paths [Hash{String => Array<String>}]
+    # @return [String, nil] the resolved path if exactly one match, nil otherwise
+    def resolve_rdoc_by_basename(path, rdoc_basename_to_paths)
+      basename = File.basename(path)
+      candidates = rdoc_basename_to_paths[basename]
+      candidates.first if candidates&.size == 1
+    end
+
+    # Normalize a file path, resolving . and .. components.
+    #
+    # @param path [String] the path to normalize
+    # @return [String] the normalized path
+    def normalize_path(path)
+      parts = path.split('/')
+      result = []
+
+      parts.each do |part|
+        case part
+        when '.', ''
+          # Skip current directory markers and empty parts
+          next
+        when '..'
+          # Go up one directory
+          result.pop
+        else
+          result << part
+        end
+      end
+
+      result.join('/')
+    end
+  end
+
+  Templates::Template.extra_includes << RelativeMarkdownLinks
+end

data/lib/yard-markdown-relative-links.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'yard/relative_markdown_links'

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: yard-markdown-relative-links
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Daniel Harrington
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: |
+  A YARD plugin that converts relative Markdown links to work in generated documentation.
+  Supports files in subdirectories by resolving links relative to the current file's location.
+  Works seamlessly with GitHub-style relative links while generating correct YARD file references.
+email:
+- me@rubiii.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- lib/yard-markdown-relative-links.rb
+- lib/yard/relative_markdown_links.rb
+- lib/yard/relative_markdown_links/version.rb
+homepage: https://github.com/rubiii/yard-markdown-relative-links
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rubiii/yard-markdown-relative-links
+  source_code_uri: https://github.com/rubiii/yard-markdown-relative-links
+  changelog_uri: https://github.com/rubiii/yard-markdown-relative-links/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rubiii/yard-markdown-relative-links/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A YARD plugin to convert relative links between Markdown files
+test_files: []