diff --git a/man/crystal.1 b/man/crystal.1
index c13644503021..56af04ebdf40 100644
--- 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
index 573bb3a4fc63..b17d652d5af9 100644
--- 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
index ed691f057bab..f4b7e2715498 100644
--- 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
index bf669a247638..5a1118e957e1 100644
--- 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
index cabc9c0f1133..c29c70867229 100644
--- 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
index 39a55dbf5acc..028a381b5ac2 100644
--- 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
index a4ff1d4b4553..b6e8a663983d 100644
--- 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
 
