Add notebook-links

Author: dragonstyle

src/config/constants.ts

@@ -39,6 +39,7 @@ export const kResources = "resources";
 export const kFormatResources = "format-resources";
 
 export const kFormatLinks = "format-links";
+export const kNotebookLinks = "notebook-links";
 
 export const kKeepHidden = "keep-hidden";
 
@@ -166,6 +167,7 @@ export const kRenderDefaultsKeys = [
   kLinkExternalFilter,
   kFormatResources,
   kFormatLinks,
+  kNotebookLinks,
 ];
 
 // language fields

src/config/types.ts

@@ -128,6 +128,7 @@ import {
   kMathml,
   kMergeIncludes,
   kMermaidFormat,
+  kNotebookLinks,
   kNumberOffset,
   kNumberSections,
   kOutput,
@@ -396,6 +397,7 @@ export interface FormatRender {
   [kSelfContainedMath]?: boolean;
   [kFormatResources]?: string[];
   [kFormatLinks]?: boolean | string[];
+  [kNotebookLinks]?: boolean | "inline" | "global";
 }
 
 export interface FormatExecute {

src/format/html/format-html-bootstrap.ts

@@ -19,6 +19,7 @@ import {
   kHtmlMathMethod,
   kIncludeInHeader,
   kLinkCitations,
+  kNotebookLinks,
   kQuartoTemplateParams,
   kRelatedFormatsTitle,
   kRelatedNotebooksTitle,
@@ -327,7 +328,9 @@ function bootstrapHtmlPostprocessor(
     }
 
     // Look for included / embedded notebooks and include those
-    processNotebookEmbeds(doc, format, resources);
+    if (format.render[kNotebookLinks] !== false) {
+      processNotebookEmbeds(doc, format, resources);
+    }
 
     // default treatment for computational tables
     const addTableClasses = (table: Element, computational = false) => {
@@ -540,6 +543,11 @@ function processNotebookEmbeds(
   format: Format,
   resources: string[],
 ) {
+  const inline = format.render[kNotebookLinks] === "inline" ||
+    format.render[kNotebookLinks] === true;
+  const global = format.render[kNotebookLinks] === "global" ||
+    format.render[kNotebookLinks] === true;
+
   const notebookDivNodes = doc.querySelectorAll("[data-notebook]");
   if (notebookDivNodes.length > 0) {
     const nbPaths: { path: string; title: string; filename: string }[] = [];
@@ -560,75 +568,79 @@ function processNotebookEmbeds(
         nbPaths.push(nbPath);
 
         // Add a decoration to this div node
-        const id = "nblink-" + count++;
-
-        const nbLinkEl = doc.createElement("a");
-        nbLinkEl.classList.add("quarto-notebook-link");
-        nbLinkEl.setAttribute("id", `${id}`);
-        nbLinkEl.setAttribute("href", nbPath.path);
-        nbLinkEl.setAttribute("download", nbPath.filename);
-        nbLinkEl.appendChild(
-          doc.createTextNode(
-            `${format.language[kSourceNotebookPrefix]}: ${nbPath.title}`,
-          ),
-        );
+        if (inline) {
+          const id = "nblink-" + count++;
+
+          const nbLinkEl = doc.createElement("a");
+          nbLinkEl.classList.add("quarto-notebook-link");
+          nbLinkEl.setAttribute("id", `${id}`);
+          nbLinkEl.setAttribute("href", nbPath.path);
+          nbLinkEl.setAttribute("download", nbPath.filename);
+          nbLinkEl.appendChild(
+            doc.createTextNode(
+              `${format.language[kSourceNotebookPrefix]}: ${nbPath.title}`,
+            ),
+          );
 
-        // If there is a figure caption, place the source after that
-        // otherwise just place it at the bottom of the notebook div
-        const nbParentEl = nbDivEl.parentElement;
-        if (nbParentEl?.tagName.toLocaleLowerCase() === "figure") {
-          const figCapEl = nbDivEl.parentElement?.querySelector("figcaption");
-          if (figCapEl) {
-            figCapEl.after(nbLinkEl);
+          // If there is a figure caption, place the source after that
+          // otherwise just place it at the bottom of the notebook div
+          const nbParentEl = nbDivEl.parentElement;
+          if (nbParentEl?.tagName.toLocaleLowerCase() === "figure") {
+            const figCapEl = nbDivEl.parentElement?.querySelector("figcaption");
+            if (figCapEl) {
+              figCapEl.after(nbLinkEl);
+            } else {
+              nbDivEl.appendChild(nbLinkEl);
+            }
           } else {
             nbDivEl.appendChild(nbLinkEl);
           }
-        } else {
-          nbDivEl.appendChild(nbLinkEl);
         }
       }
     });
 
-    const containerEl = doc.createElement("div");
-    containerEl.classList.add("quarto-alternate-notebooks");
+    if (global) {
+      const containerEl = doc.createElement("div");
+      containerEl.classList.add("quarto-alternate-notebooks");
 
-    const heading = doc.createElement("h2");
-    if (format.language[kRelatedNotebooksTitle]) {
-      heading.innerText = format.language[kRelatedNotebooksTitle];
-    }
-    containerEl.appendChild(heading);
-
-    const formatList = doc.createElement("ul");
-    containerEl.appendChild(formatList);
-    ld.uniqBy(nbPaths, (nbPath: { path: string; title?: string }) => {
-      return nbPath.path;
-    }).forEach((nbPath) => {
-      const li = doc.createElement("li");
-
-      const link = doc.createElement("a");
-      link.setAttribute("href", nbPath.path);
-      link.setAttribute("download", nbPath.filename);
-
-      const icon = doc.createElement("i");
-      icon.classList.add("bi");
-      icon.classList.add(`bi-journal-code`);
-      link.appendChild(icon);
-      link.appendChild(
-        doc.createTextNode(nbPath.title),
-      );
+      const heading = doc.createElement("h2");
+      if (format.language[kRelatedNotebooksTitle]) {
+        heading.innerText = format.language[kRelatedNotebooksTitle];
+      }
+      containerEl.appendChild(heading);
 
-      li.appendChild(link);
-      formatList.appendChild(li);
+      const formatList = doc.createElement("ul");
+      containerEl.appendChild(formatList);
+      ld.uniqBy(nbPaths, (nbPath: { path: string; title?: string }) => {
+        return nbPath.path;
+      }).forEach((nbPath) => {
+        const li = doc.createElement("li");
+
+        const link = doc.createElement("a");
+        link.setAttribute("href", nbPath.path);
+        link.setAttribute("download", nbPath.filename);
+
+        const icon = doc.createElement("i");
+        icon.classList.add("bi");
+        icon.classList.add(`bi-journal-code`);
+        link.appendChild(icon);
+        link.appendChild(
+          doc.createTextNode(nbPath.title),
+        );
 
-      resources.push(nbPath.path);
-    });
-    let dlLinkTarget = doc.querySelector(`nav[role="doc-toc"]`);
-    if (dlLinkTarget === null) {
-      dlLinkTarget = doc.querySelector("#quarto-margin-sidebar");
-    }
+        li.appendChild(link);
+        formatList.appendChild(li);
 
-    if (dlLinkTarget) {
-      dlLinkTarget.appendChild(containerEl);
+        resources.push(nbPath.path);
+      });
+      let dlLinkTarget = doc.querySelector(`nav[role="doc-toc"]`);
+      if (dlLinkTarget === null) {
+        dlLinkTarget = doc.querySelector("#quarto-margin-sidebar");
+      }
+
+      if (dlLinkTarget) {
+        dlLinkTarget.appendChild(containerEl);
+      }
     }
   }
 }

src/format/html/format-html.ts

@@ -20,12 +20,14 @@ import {
   kCodeLink,
   kFigResponsive,
   kFilterParams,
+  kFormatLinks,
   kHeaderIncludes,
   kIncludeAfterBody,
   kIncludeInHeader,
   kLinkExternalFilter,
   kLinkExternalIcon,
   kLinkExternalNewwindow,
+  kNotebookLinks,
   kTheme,
 } from "../../config/constants.ts";
 
@@ -94,6 +96,10 @@ export function htmlFormat(
   return mergeConfigs(
     createHtmlFormat("HTML", figwidth, figheight),
     {
+      render: {
+        [kNotebookLinks]: true,
+        [kFormatLinks]: true,
+      },
       resolveFormat: (format: Format) => {
         if (format.metadata[kMinimal] === true) {
           if (format.metadata[kFigResponsive] === undefined) {

src/resources/schema/document-links.yml

@@ -39,3 +39,18 @@
 
       Pass `false` to disable the display of format lengths or pass a list of format names for which you'd
       like links to be shown.
+
+- name: notebook-links
+  tags:
+    formats: [$html-doc]
+  schema:
+    anyOf:
+      - boolean
+      - enum: [inline, global]
+  description:
+    short: "Controls the display of links to notebooks that provided embedded content or are created from documents."
+    long: |
+      Controls the display of links to notebooks that provided embedded content or are created from documents.
+
+      Specify `false` to disable linking to source Notebooks. Specify `inline` to show links to source notebooks beneath the content they provide. 
+      Specify `global` to show a set of global links to source notebooks.