gleam-lang · lpil · Dec 10, 2024 · Nov 21, 2024 · Dec 2, 2024 · Dec 4, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -175,6 +175,13 @@
 - The formatter now adds a `todo` inside empty blocks.
   ([Giacomo Cavalieri](https://github.com/giacomocavalieri))
 
+### Documentation
+
+- Canonical links created for documentation pages if published on Hex. Previously
+  published documentation would need to be updated. Resolves versioned pages to point
+  to latest page for search engines.
+  ([Dave Lage](https://github.com/rockerBOO))
+
 ### Bug fixed
 
 - The compiler now throws an error when a float literal ends with an `e` and

diff --git a/compiler-core/src/docs.rs b/compiler-core/src/docs.rs
@@ -74,6 +74,12 @@ pub fn generate_html<IO: FileSystemReader>(
         path,
     });
 
+    let host = if is_hex_publish == DocContext::HexPublish {
+        "https://hexdocs.pm"
+    } else {
+        ""
+    };
+
     // https://github.com/gleam-lang/gleam/issues/3020
     let links: Vec<_> = match is_hex_publish {
         DocContext::HexPublish => doc_links
@@ -119,6 +125,7 @@ pub fn generate_html<IO: FileSystemReader>(
             "index" => config.description.to_string().clone(),
             _other => "".to_owned(),
         };
+        let path = Utf8PathBuf::from(&page.path);
 
         let temp = PageTemplate {
             gleam_version: COMPILER_VERSION,
@@ -128,14 +135,16 @@ pub fn generate_html<IO: FileSystemReader>(
             project_name: &config.name,
             page_title: &page_title,
             page_meta_description: &page_meta_description,
+            file_path: &path.clone(),
             project_version: &config.version.to_string(),
             content: rendered_content,
             rendering_timestamp: &rendering_timestamp,
+            host,
             unnest: &unnest,
         };
 
         files.push(OutputFile {
-            path: Utf8PathBuf::from(&page.path),
+            path,
             content: Content::Text(temp.render().expect("Page template rendering")),
         });
 
@@ -252,9 +261,11 @@ pub fn generate_html<IO: FileSystemReader>(
 
         let page_title = format!("{} · {} · v{}", name, config.name, config.version);
         let page_meta_description = "";
+        let path = Utf8PathBuf::from(format!("{}.html", module.name));
 
         let template = ModuleTemplate {
             gleam_version: COMPILER_VERSION,
+            host,
             unnest,
             links: &links,
             pages: &pages,
@@ -263,7 +274,8 @@ pub fn generate_html<IO: FileSystemReader>(
             project_name: &config.name,
             page_title: &page_title,
             page_meta_description,
-            module_name: name,
+            module_name: EcoString::from(&name),
+            file_path: &path.clone(),
             project_version: &config.version.to_string(),
             functions,
             types,
@@ -272,7 +284,7 @@ pub fn generate_html<IO: FileSystemReader>(
         };
 
         files.push(OutputFile {
-            path: Utf8PathBuf::from(format!("{}.html", module.name)),
+            path,
             content: Content::Text(
                 template
                     .render()
@@ -776,8 +788,10 @@ struct Constant<'a> {
 struct PageTemplate<'a> {
     gleam_version: &'a str,
     unnest: &'a str,
+    host: &'a str,
     page_title: &'a str,
     page_meta_description: &'a str,
+    file_path: &'a Utf8PathBuf,
     project_name: &'a str,
     project_version: &'a str,
     pages: &'a [Link],
@@ -792,8 +806,10 @@ struct PageTemplate<'a> {
 struct ModuleTemplate<'a> {
     gleam_version: &'a str,
     unnest: String,
+    host: &'a str,
     page_title: &'a str,
     page_meta_description: &'a str,
+    file_path: &'a Utf8PathBuf,
     module_name: EcoString,
     project_name: &'a str,
     project_version: &'a str,

diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__canonical_link.snap
diff --git a/...r-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap b/...r-core/src/docs/snapshots/gleam_core__docs__tests__discarded_arguments_are_not_shown.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>
 

diff --git a/...core__docs__tests__docs_of_a_type_constructor_are_not_used_by_the_following_function.snap b/...core__docs__tests__docs_of_a_type_constructor_are_not_used_by_the_following_function.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>
 

diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__hello_docs.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__hello_docs.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>
 

diff --git a/...re/src/docs/snapshots/gleam_core__docs__tests__internal_definitions_are_not_included.snap b/...re/src/docs/snapshots/gleam_core__docs__tests__internal_definitions_are_not_included.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>
 

diff --git a/compiler-core/src/docs/snapshots/gleam_core__docs__tests__long_function_wrapping.snap b/compiler-core/src/docs/snapshots/gleam_core__docs__tests__long_function_wrapping.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>
 

diff --git a/...cs/snapshots/gleam_core__docs__tests__markdown_code_from_function_comment_is_trimmed.snap b/...cs/snapshots/gleam_core__docs__tests__markdown_code_from_function_comment_is_trimmed.snap
@@ -9,7 +9,7 @@ expression: "compile(config, modules)"
   <head>
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1"/>
-    <title>app ·  · v0.1.0</title>
+    <title>app · test_project_name · v0.1.0</title>
     <meta name="description" content=""/>
     <meta name="theme-color" content="#ffaff3" media="(prefers-color-scheme: light)"/>
     <meta name="theme-color" content="#33384d" media="(prefers-color-scheme: dark)"/>
@@ -18,6 +18,7 @@ expression: "compile(config, modules)"
          between multiple versions of the same package. -->
     <script src="./docs_config.js"></script>
     <link id="syntax-theme" rel="stylesheet" href="./css/atom-one-light.min.css?v=GLEAM_VERSION_HERE"/>
+    <link rel="canonical" href="https://hexdocs.pm/test_project_name/app.html" />
   </head>
   <body class="prewrap-off theme-light drawer-closed">
     <script>
@@ -148,7 +149,7 @@ expression: "compile(config, modules)"
       </button>
 
       <h2>
-        <a href="./"></a>
+        <a href="./">test_project_name</a>
         <span id="project-version">
           <span> - v0.1.0 </span>
         </span>
@@ -186,7 +187,7 @@ expression: "compile(config, modules)"
       </h2>
       <div class="search">
         <div class="search-input-wrap">
-          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search " autocomplete="off">
+          <input type="text" id="search-input" class="search-input" tabindex="0" aria-label="Search test_project_name" autocomplete="off">
           <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#icon-svg-search"></use></svg></label>
         </div>
         <div id="search-results" class="search-results"></div>
@@ -210,7 +211,7 @@ expression: "compile(config, modules)"
         <h2>Links</h2>
         <ul>
 
-          <li><a href="https://hex.pm/packages/">Hex</a></li>
+          <li><a href="https://hex.pm/packages/test_project_name">Hex</a></li>
 
         </ul>