Add --base-path for crystal docs (#16091)

matiasgarciaisaia · Sija · straight-shoota · web-flow · commit 8afd5be1f4c5 · 2026-01-27T12:14:59.000+01:00
The 404 page of the docs is served at different (sub)paths in a website, relative references to assets (CSS and JS files) don't work for subdirectories and we must set a base href to correctly resolve relative URLs.

Co-authored-by: Sijawusz Pur Rahnama &lt;sija@sija.pl&gt;
Co-authored-by: Johannes Müller &lt;straightshoota@gmail.com&gt;
diff --git a/src/compiler/crystal/command/docs.cr b/src/compiler/crystal/command/docs.cr
@@ -60,6 +60,10 @@ class Crystal::Command
         project_info.canonical_base_url = value
       end
 
+      opts.on("--base-path=PATH", "Set the base path - must be absolute for finding assets on the 404 page") do |value|
+        project_info.base_path = value
+      end
+
       opts.on("--sitemap-base-url=URL", "-b URL", "Set the sitemap base URL and generates sitemap") do |value|
         sitemap_base_url = value
       end
diff --git a/src/compiler/crystal/tools/doc/generator.cr b/src/compiler/crystal/tools/doc/generator.cr
@@ -91,7 +91,7 @@ class Crystal::Doc::Generator
     File.write File.join(@output_dir, "index.json"), main_index
     File.write File.join(@output_dir, "search-index.js"), main_index.to_jsonp
 
-    File.write File.join(@output_dir, "404.html"), MainTemplate.new(Error404Template.new.to_s, types, project_info)
+    File.write File.join(@output_dir, "404.html"), MainTemplate.new(Error404Template.new.to_s, types, project_info, base_path: project_info.base_path)
   end
 
   def generate_sitemap(types)
diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html
@@ -1,6 +1,9 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
+  <%- if base_path = self.base_path -%>
+  <base href="<%= base_path %>" />
+  <%- end -%>
   <%= HeadTemplate.new(project_info, nil) %>
   <meta name="repository-name" content="<%= project_info.name %>">
   <title><%= project_info.name %> <%= project_info.version %></title>
diff --git a/src/compiler/crystal/tools/doc/project_info.cr b/src/compiler/crystal/tools/doc/project_info.cr
@@ -6,6 +6,7 @@ module Crystal::Doc
     property refname : String? = nil
     property source_url_pattern : String? = nil
     property canonical_base_url : String? = nil
+    property base_path : 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
@@ -57,7 +57,7 @@ module Crystal::Doc
     ECR.def_to_s "#{__DIR__}/html/_other_types.html"
   end
 
-  record MainTemplate, body : String, types : Array(Type), project_info : ProjectInfo do
+  record MainTemplate, body : String, types : Array(Type), project_info : ProjectInfo, base_path : String? = nil do
     ECR.def_to_s "#{__DIR__}/html/main.html"
   end
 
