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 <[email protected]>

Author: p8

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

lib/rdoc/generator/template/darkfish/_head.rhtml

@@ -25,6 +25,11 @@
   <%- end -%>
 <%- end -%>
 
+<%- if @options.canonical_root -%>
+<% path = defined?(current) ? current.canonical_url : @options.canonical_root %>
+<link rel="canonical" href="<%= path %>">
+<%- end -%>
+
 <script type="text/javascript">
   var rdoc_rel_prefix = "<%= h asset_rel_prefix %>/";
   var index_rel_prefix = "<%= h rel_prefix %>/";

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')
 

test/rdoc/test_rdoc_generator_darkfish.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.

test/rdoc/test_rdoc_options.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