Re-introduce canonical URL for docs generator (#9917)

The previous attempt to use sitemaps to indicate preference of latest version over older ones to search engines doesn't seem to work. Instead, the solution applied for similar situations is canonical links. This mostly reinstates the canonical link behaviour prior to #8348
crystal-lang · Dec 1, 2020 · c7392a0 · c7392a0
1 parent 4c9072e
commit c7392a0
Show file tree

Hide file tree

Showing 7 changed files with 24 additions and 5 deletions.
diff --git a/man/crystal.1 b/man/crystal.1
@@ -208,6 +208,8 @@ line number
 If this option is missing and can't be automatically determined, the generator can't produce source code links.
 .It Fl o Ar DIR, Fl -output Ar DIR
 Set the output directory (default: ./docs).
+.It Fl b Ar URL, Fl -canonical-base-url Ar URL
+Indicate the preferred URL with rel="canonical" link element.
 .It Fl b Ar URL, Fl -sitemap-base-url Ar URL
 Set the sitemap base URL. Sitemap will only be generated when this option is set.
 .It Fl -sitemap-priority Ar PRIO

diff --git a/src/compiler/crystal/command/docs.cr b/src/compiler/crystal/command/docs.cr
@@ -56,8 +56,8 @@ class Crystal::Command
         project_info.json_config_url = value
       end
 
-      opts.on("--canonical-base-url=URL", "Deprecated option. Use --sitemap-base-url instead.") do |value|
-        abort "Option --canonical-base-url is no longer supported.  Use --sitemap-base-url instead."
+      opts.on("--canonical-base-url=URL", %(Indicate the preferred URL with rel="canonical" link element)) do |value|
+        project_info.canonical_base_url = value
       end
 
       opts.on("--sitemap-base-url=URL", "-b URL", "Set the sitemap base URL and generates sitemap") do |value|

diff --git a/src/compiler/crystal/tools/doc/html/_head.html b/src/compiler/crystal/tools/doc/html/_head.html
@@ -7,5 +7,13 @@
   <meta name="crystal_docs.json_config_url" content="<%= json_config_url %>">
 <% end %>
 
+<%- if canonical_base_url = project_info.canonical_base_url -%>
+  <%- if current_type = self.current_type -%>
+    <link rel="canonical" href="<%= ::Path.posix(canonical_base_url, current_type.path) %>">
+  <%- else -%>
+    <link rel="canonical" href="<%= canonical_base_url %>">
+  <% end -%>
+<% end -%>
+
 <link href="<%= base_path %>css/style.css" rel="stylesheet" type="text/css" />
 <script type="text/javascript" src="<%= base_path %>js/doc.js"></script>
diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <%= HeadTemplate.new(project_info, "") %>
+  <%= HeadTemplate.new(project_info, nil) %>
   <meta name="repository-name" content="<%= project_info.name %>">
   <title><%= project_info.name %> <%= project_info.version %></title>
   <script type="text/javascript">

diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <%= HeadTemplate.new(project_info, type.path_to "") %>
+  <%= HeadTemplate.new(project_info, type) %>
   <meta name="repository-name" content="<%= project_info.name %>">
   <title><%= type.full_name %> - <%= project_info.name %> <%= project_info.version %></title>
   <script type="text/javascript">

diff --git a/src/compiler/crystal/tools/doc/project_info.cr b/src/compiler/crystal/tools/doc/project_info.cr
@@ -5,6 +5,7 @@ module Crystal::Doc
     property json_config_url : String? = nil
     property refname : String? = nil
     property source_url_pattern : String? = nil
+    property canonical_base_url : String? = nil
 
     def initialize(@name : String? = nil, @version : String? = nil, @refname : String? = nil, @source_url_pattern : String? = nil)
     end

diff --git a/src/compiler/crystal/tools/doc/templates.cr b/src/compiler/crystal/tools/doc/templates.cr
@@ -49,7 +49,15 @@ module Crystal::Doc
     ECR.def_to_s "#{__DIR__}/html/main.html"
   end
 
-  record HeadTemplate, project_info : ProjectInfo, base_path : String do
+  record HeadTemplate, project_info : ProjectInfo, current_type : Type? do
+    def base_path
+      if current_type = self.current_type
+        current_type.path_to ""
+      else
+        ""
+      end
+    end
+
     ECR.def_to_s "#{__DIR__}/html/_head.html"
   end