Add support for canonical URL link tag (ruby#1354)

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:

```html
<link rel="canonical" href="https://docs.ruby-lang.org/en/master/String.html">
```

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 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 %>/";

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/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.

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