From cec51e3fa3c7b38c79e7804a2a42286bd2f77d0b Mon Sep 17 00:00:00 2001
From: Petrik <petrik@deheus.net>
Date: Thu, 1 May 2025 12:27:55 +0200
Subject: [PATCH] Add support for canonical URL link

Currently, search engines don't know which version to show for API
documentation. For example, searching for "ruby string" in Google will
show the documentation for Ruby 2.0
`https://docs.ruby-lang.org/en/2.0.0/String.html` as the top result (for
docs.ruby-lang.org).

The canonical URL link tag will allow us to set the preferred version:

> The canonical URL link tag defines the preferred URL for the current
> document, which helps search engines reduce duplicate content.

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel#canonical

For example, for the official Ruby documentation we can add the
following to `.rdoc_options`.

```yaml
canonical_root: https://docs.ruby-lang.org/en/master
```

This will add the canonical URL link tag to relevant pages.

Co-authored-by: Stan Lo <stan001212@gmail.com>
---
 lib/rdoc/generator/markup.rb                  | 12 +++++++
 .../generator/template/darkfish/_head.rhtml   |  5 +++
 lib/rdoc/options.rb                           |  7 ++++
 test/rdoc/rdoc_generator_darkfish_test.rb     | 33 +++++++++++++++++++
 test/rdoc/rdoc_options_test.rb                |  1 +
 5 files changed, 58 insertions(+)

diff --git a/lib/rdoc/generator/markup.rb b/lib/rdoc/generator/markup.rb
index 206b3c53d4..1c39687040 100644
--- a/lib/rdoc/generator/markup.rb
+++ b/lib/rdoc/generator/markup.rb
@@ -55,6 +55,18 @@ def cvs_url(url, full_path)
     end
   end
 
+  ##
+  # The preferred URL for this object.
+
+  def canonical_url
+    options = @store.options
+    if path
+      File.join(options.canonical_root, path.to_s)
+    else
+      options.canonical_root
+    end
+  end
+
 end
 
 class RDoc::CodeObject
diff --git a/lib/rdoc/generator/template/darkfish/_head.rhtml b/lib/rdoc/generator/template/darkfish/_head.rhtml
index 9e6fb4f94c..7376fc390e 100644
--- a/lib/rdoc/generator/template/darkfish/_head.rhtml
+++ b/lib/rdoc/generator/template/darkfish/_head.rhtml
@@ -25,6 +25,11 @@
   <%- end -%>
 <%- end -%>
 
+<%- if canonical_url = @options.canonical_root -%>
+<% canonical_url = current.canonical_url if defined?(current) %>
+<link rel="canonical" href="<%= canonical_url %>">
+<%- end -%>
+
 <script type="text/javascript">
   var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
   var index_rel_prefix = "<%= h rel_prefix %>/";
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb
index bd33d4c3b2..9ab0385bfa 100644
--- a/lib/rdoc/options.rb
+++ b/lib/rdoc/options.rb
@@ -373,6 +373,11 @@ class RDoc::Options
 
   attr_accessor :file_path_prefix
 
+  ##
+  # The preferred root URL for the documentation
+
+  attr_accessor :canonical_root
+
   def initialize(loaded_options = nil) # :nodoc:
     init_ivars
     override loaded_options if loaded_options
@@ -429,6 +434,7 @@ def init_ivars # :nodoc:
     @apply_default_exclude = true
     @class_module_path_prefix = nil
     @file_path_prefix = nil
+    @canonical_root = nil
   end
 
   def init_with(map) # :nodoc:
@@ -492,6 +498,7 @@ def override(map) # :nodoc:
     @webcvs         = map['webcvs']         if map.has_key?('webcvs')
     @autolink_excluded_words = map['autolink_excluded_words'] if map.has_key?('autolink_excluded_words')
     @apply_default_exclude = map['apply_default_exclude'] if map.has_key?('apply_default_exclude')
+    @canonical_root = map['canonical_root'] if map.has_key?('canonical_root')
 
     @warn_missing_rdoc_ref = map['warn_missing_rdoc_ref'] if map.has_key?('warn_missing_rdoc_ref')
 
diff --git a/test/rdoc/rdoc_generator_darkfish_test.rb b/test/rdoc/rdoc_generator_darkfish_test.rb
index 580d25b360..de95e8b5e1 100644
--- a/test/rdoc/rdoc_generator_darkfish_test.rb
+++ b/test/rdoc/rdoc_generator_darkfish_test.rb
@@ -514,6 +514,39 @@ def test_meta_tags_for_empty_document
     )
   end
 
+  def test_canonical_url_for_index
+    @store.options.canonical_root = @options.canonical_root = "https://docs.ruby-lang.org/en/master/"
+    @g.generate
+
+    content = File.binread("index.html")
+
+    assert_include(content, '<link rel="canonical" href="https://docs.ruby-lang.org/en/master/">')
+  end
+
+  def test_canonical_url_for_classes
+    top_level = @store.add_file("file.rb")
+    top_level.add_class(@klass.class, @klass.name)
+    inner = @klass.add_class(RDoc::NormalClass, "Inner")
+
+    @store.options.canonical_root = @options.canonical_root = "https://docs.ruby-lang.org/en/master/"
+    @g.generate
+
+    content = File.binread("Klass/Inner.html")
+
+    assert_include(content, '<link rel="canonical" href="https://docs.ruby-lang.org/en/master/Klass/Inner.html">')
+  end
+
+  def test_canonical_url_for_rdoc_files
+    top_level = @store.add_file("CONTRIBUTING.rdoc", parser: RDoc::Parser::Simple)
+
+    @store.options.canonical_root = @options.canonical_root = "https://docs.ruby-lang.org/en/master/"
+    @g.generate
+
+    content = File.binread("CONTRIBUTING_rdoc.html")
+
+    assert_include(content, '<link rel="canonical" href="https://docs.ruby-lang.org/en/master/CONTRIBUTING_rdoc.html">')
+  end
+
   ##
   # Asserts that +filename+ has a link count greater than 1 if hard links to
   # @tmpdir are supported.
diff --git a/test/rdoc/rdoc_options_test.rb b/test/rdoc/rdoc_options_test.rb
index 0300d3fce1..097d0f5523 100644
--- a/test/rdoc/rdoc_options_test.rb
+++ b/test/rdoc/rdoc_options_test.rb
@@ -89,6 +89,7 @@ def test_to_yaml
       'autolink_excluded_words' => [],
       'class_module_path_prefix' => nil,
       'file_path_prefix' => nil,
+      'canonical_root' => nil,
     }
 
     assert_equal expected, coder