Add support for canonical-url

The canonical url provides a way for users to either provide an explicit canonical url or to have Quarto automatically generate a canonical url.

See discussion #3976

Fixes #4882

Author: dragonstyle

news/changelog-1.4.md

@@ -19,6 +19,7 @@
 - Add support for showing cross reference contents on hover (use `crossrefs-hover: false` to disable).
 - Add support for displaying `keywords` in HTML page title block, when present.
 - ([#3473](https://github.com/quarto-dev/quarto-cli/issues/3473)): Add support for `body-right` and `body-left` layouts for Website Table of Contents.
+- ([#4882](https://github.com/quarto-dev/quarto-cli/issues/4882)): Add support for `canonical-url`, which when provided will include a link tag with rel='canonical' which will use an explictly provided or automatically generated canonical url for the document.
 - ([#5189](https://github.com/quarto-dev/quarto-cli/issues/5189)): Ensure appendix shows even when `page-layout` is custom.
 - ([#5210](https://github.com/quarto-dev/quarto-cli/issues/5210)): Update to Bootstrap 5.2.2
 - ([#5393](https://github.com/quarto-dev/quarto-cli/issues/5393)): Properly set color of headings without using opacity.

src/config/constants.ts

@@ -54,6 +54,7 @@ export const kNotebookPreserveCells = "notebook-preserve-cells";
 export const kClearCellOptions = "clear-cell-options";
 export const kDownloadUrl = "download-url";
 export const kLightbox = "lightbox";
+export const kCanonicalUrl = "canonical-url";
 
 export const kMath = "math";
 
@@ -223,6 +224,7 @@ export const kRenderDefaultsKeys = [
   kClearCellOptions,
   kHtmlTableProcessing,
   kValidateYaml,
+  kCanonicalUrl,
 ];
 
 // language fields

src/config/types.ts

@@ -17,6 +17,7 @@ import {
   kCalloutNoteCaption,
   kCalloutTipCaption,
   kCalloutWarningCaption,
+  kCanonicalUrl,
   kCiteMethod,
   kCiteproc,
   kClearCellOptions,
@@ -477,6 +478,7 @@ export interface FormatRender {
   [kIpynbProduceSourceNotebook]?: boolean;
   [kHtmlTableProcessing]?: "none";
   [kValidateYaml]?: boolean;
+  [kCanonicalUrl]?: boolean | string;
 }
 
 export interface FormatExecute {

src/format/html/format-html-meta.ts

@@ -1,15 +1,15 @@
 /*
-* format-html-meta.ts
-*
-* Copyright (C) 2020-2022 Posit Software, PBC
-*
-*/
+ * format-html-meta.ts
+ *
+ * Copyright (C) 2020-2022 Posit Software, PBC
+ */
 
 import { kHtmlEmptyPostProcessResult } from "../../command/render/constants.ts";
 import {
   PandocInputTraits,
   RenderedFormat,
 } from "../../command/render/types.ts";
+import { kCanonicalUrl } from "../../config/constants.ts";
 import { Format, Metadata } from "../../config/types.ts";
 import { bibliographyCslJson } from "../../core/bibliography.ts";
 import {
@@ -23,8 +23,11 @@ import {
 import { Document } from "../../core/deno-dom.ts";
 import { encodeAttributeValue } from "../../core/html.ts";
 import { kWebsite } from "../../project/types/website/website-constants.ts";
-import { documentCSL } from "../../quarto-core/attribution/document.ts";
-import { writeMetaTag } from "./format-html-shared.ts";
+import {
+  documentCSL,
+  synthesizeCitationUrl,
+} from "../../quarto-core/attribution/document.ts";
+import { writeLinkTag, writeMetaTag } from "./format-html-shared.ts";
 
 export const kGoogleScholar = "google-scholar";
 
@@ -38,6 +41,18 @@ export function metadataPostProcessor(
     inputTraits: PandocInputTraits;
     renderedFormats: RenderedFormat[];
   }) => {
+    // Generate a canonical tag if requested
+    if (format.render[kCanonicalUrl]) {
+      writeCanonicalUrl(
+        doc,
+        format.render[kCanonicalUrl],
+        input,
+        options.inputMetadata,
+        format.pandoc["output-file"],
+        offset,
+      );
+    }
+
     if (googleScholarEnabled(format)) {
       const { csl, extras } = documentCSL(
         input,
@@ -269,3 +284,28 @@ function metadataWriter(metadata: MetaTagData[]) {
   };
   return write;
 }
+
+function writeCanonicalUrl(
+  doc: Document,
+  url: string | boolean,
+  input: string,
+  inputMetadata: Metadata,
+  outputFile?: string,
+  offset?: string,
+) {
+  if (typeof url === "string") {
+    // Use the explicitly provided URL
+    writeLinkTag("canonical", url, doc);
+  } else if (url) {
+    // Compute a canonical url and include that
+    const canonicalUrl = synthesizeCitationUrl(
+      input,
+      inputMetadata,
+      outputFile,
+      offset,
+    );
+    if (canonicalUrl) {
+      writeLinkTag("canonical", canonicalUrl, doc);
+    }
+  }
+}

src/format/html/format-html-shared.ts

@@ -390,7 +390,7 @@ function prependHeading(
   classes: string[],
 ) {
   const heading = doc.createElement("h" + level);
-  if (typeof (title) == "string" && title !== "none") {
+  if (typeof title == "string" && title !== "none") {
     heading.innerHTML = title;
   }
   if (classes) {
@@ -515,6 +515,20 @@ export function writeMetaTag(name: string, content: string, doc: Document) {
   doc.querySelector("head")?.appendChild(nl);
 }
 
+export function writeLinkTag(rel: string, href: string, doc: Document) {
+  // Meta tag
+  const l = doc.createElement("LINK");
+  l.setAttribute("rel", rel);
+  l.setAttribute("href", href);
+
+  // New Line
+  const nl = doc.createTextNode("\n");
+
+  // Insert the nodes
+  doc.querySelector("head")?.appendChild(l);
+  doc.querySelector("head")?.appendChild(nl);
+}
+
 export function formatPageLayout(format: Format) {
   return format.metadata[kPageLayout] as string || kPageLayoutArticle;
 }

src/quarto-core/attribution/document.ts

@@ -435,7 +435,7 @@ export function citationMeta(metadata: Metadata): Metadata {
   }
 }
 
-function synthesizeCitationUrl(
+export function synthesizeCitationUrl(
   input: string,
   metadata: Metadata,
   outputFile?: string,

src/resources/editor/tools/vs-code.mjs

@@ -15237,6 +15237,24 @@ var require_yaml_intelligence_resources = __commonJS({
             }
           },
           description: "Options for controlling the display and behavior of Notebook previews."
+        },
+        {
+          "canonical-url": null,
+          tags: {
+            formats: [
+              "$html-doc"
+            ]
+          },
+          schema: {
+            anyOf: [
+              "boolean",
+              "string"
+            ]
+          },
+          description: {
+            short: "Include a canonical link tag in website pages",
+            long: "Include a canonical link tag in website pages. You may pass either `true` to \nautomatically generate a canonical link, or pass a canonical url that you'd like\nto have placed in the `href` attribute of the tag.\n\nCanonical links can only be generated for websites with a known `site-url`.\n"
+          }
         }
       ],
       "schema/document-listing.yml": [
@@ -22334,7 +22352,11 @@ var require_yaml_intelligence_resources = __commonJS({
         },
         "Disambiguating year suffix in author-date styles (e.g. \u201Ca\u201D in \u201CDoe,\n1999a\u201D).",
         "Manuscript configuration",
-        "internal-schema-hack"
+        "internal-schema-hack",
+        {
+          short: "Include a canonical link tag in website pages",
+          long: "Include a canonical link tag in website pages. You may pass either\n<code>true</code> to automatically generate a canonical link, or pass a\ncanonical url that you\u2019d like to have placed in the <code>href</code>\nattribute of the tag.\nCanonical links can only be generated for websites with a known\n<code>site-url</code>."
+        }
       ],
       "schema/external-schemas.yml": [
         {
@@ -22558,12 +22580,12 @@ var require_yaml_intelligence_resources = __commonJS({
         mermaid: "%%"
       },
       "handlers/mermaid/schema.yml": {
-        _internalId: 180066,
+        _internalId: 180143,
         type: "object",
         description: "be an object",
         properties: {
           "mermaid-format": {
-            _internalId: 180058,
+            _internalId: 180135,
             type: "enum",
             enum: [
               "png",
@@ -22579,7 +22601,7 @@ var require_yaml_intelligence_resources = __commonJS({
             exhaustiveCompletions: true
           },
           theme: {
-            _internalId: 180065,
+            _internalId: 180142,
             type: "anyOf",
             anyOf: [
               {

src/resources/editor/tools/yaml/web-worker.js

@@ -8209,6 +8209,24 @@
         }
       },
       "description": "Options for controlling the display and behavior of Notebook previews."
+    },
+    {
+      "canonical-url": null,
+      "tags": {
+        "formats": [
+          "$html-doc"
+        ]
+      },
+      "schema": {
+        "anyOf": [
+          "boolean",
+          "string"
+        ]
+      },
+      "description": {
+        "short": "Include a canonical link tag in website pages",
+        "long": "Include a canonical link tag in website pages. You may pass either `true` to \nautomatically generate a canonical link, or pass a canonical url that you'd like\nto have placed in the `href` attribute of the tag.\n\nCanonical links can only be generated for websites with a known `site-url`.\n"
+      }
     }
   ],
   "schema/document-listing.yml": [
@@ -15306,7 +15324,11 @@
     },
     "Disambiguating year suffix in author-date styles (e.g. “a” in “Doe,\n1999a”).",
     "Manuscript configuration",
-    "internal-schema-hack"
+    "internal-schema-hack",
+    {
+      "short": "Include a canonical link tag in website pages",
+      "long": "Include a canonical link tag in website pages. You may pass either\n<code>true</code> to automatically generate a canonical link, or pass a\ncanonical url that you’d like to have placed in the <code>href</code>\nattribute of the tag.\nCanonical links can only be generated for websites with a known\n<code>site-url</code>."
+    }
   ],
   "schema/external-schemas.yml": [
     {
@@ -15530,12 +15552,12 @@
     "mermaid": "%%"
   },
   "handlers/mermaid/schema.yml": {
-    "_internalId": 180066,
+    "_internalId": 180143,
     "type": "object",
     "description": "be an object",
     "properties": {
       "mermaid-format": {
-        "_internalId": 180058,
+        "_internalId": 180135,
         "type": "enum",
         "enum": [
           "png",
@@ -15551,7 +15573,7 @@
         "exhaustiveCompletions": true
       },
       "theme": {
-        "_internalId": 180065,
+        "_internalId": 180142,
         "type": "anyOf",
         "anyOf": [
           {

src/resources/editor/tools/yaml/yaml-intelligence-resources.json

@@ -141,3 +141,19 @@
           boolean:
             description: "Whether to show a back button in the notebook preview."
   description: "Options for controlling the display and behavior of Notebook previews."
+
+- canonical-url:
+  tags:
+    formats: [$html-doc]
+  schema:
+    anyOf:
+      - boolean
+      - string
+  description:
+    short: "Include a canonical link tag in website pages"
+    long: |
+      Include a canonical link tag in website pages. You may pass either `true` to 
+      automatically generate a canonical link, or pass a canonical url that you'd like
+      to have placed in the `href` attribute of the tag.
+
+      Canonical links can only be generated for websites with a known `site-url`.