Improve Notebook Ordering

- If the user provides an explicit order in manuscript configuration, be sure to respect that
- If no order is provided, sort by title

Author: dragonstyle

news/changelog-1.5.md

@@ -4,6 +4,10 @@ All changes included in 1.5:
 
 - ([#8118](https://github.com/quarto-dev/quarto-cli/issues/8118)): Add support for `body-classes` to add classes to the document body.
 
+## Manuscripts
+
+- ([#8277](https://github.com/quarto-dev/quarto-cli/issues/8277)): Improve notebook ordering within Manuscript projects
+
 ## Other Fixes
 
 - ([#8119](https://github.com/quarto-dev/quarto-cli/issues/8119)): More intelligently detect when ejs templates are modified during development, improving quality of life during preview.

src/config/types.ts

@@ -343,6 +343,7 @@ export interface NotebookPreviewDescriptor {
   url?: string;
   title?: string;
   [kDownloadUrl]?: string;
+  order?: number;
 }
 
 export interface FormatExtras {

src/format/html/format-html-notebook-preview.ts

@@ -32,13 +32,15 @@ export interface NotebookPreview {
   filename?: string;
   supporting?: string[];
   resources?: string[];
+  order?: number;
 }
 
 export interface NotebookPreviewTask {
   input: string;
   nbPath: string;
   title?: string;
   nbPreviewFile?: string;
+  order?: number;
   callback?: (nbPreview: NotebookPreview) => void;
 }
 
@@ -54,7 +56,7 @@ export const notebookPreviewer = (
 
   const nbDescriptors: Record<string, NotebookPreviewDescriptor> = {};
   if (nbView) {
-    if (typeof (nbView) !== "boolean") {
+    if (typeof nbView !== "boolean") {
       asArray(nbView).forEach((view) => {
         const existingView = nbDescriptors[view.notebook];
         nbDescriptors[view.notebook] = {
@@ -74,15 +76,23 @@ export const notebookPreviewer = (
     input: string,
     nbAbsPath: string,
     title?: string,
+    order?: number,
     callback?: (nbPreview: NotebookPreview) => void,
   ) => {
-    // Try to provide a title
-    previewQueue.push({
-      input,
-      nbPath: nbAbsPath,
-      title: title,
-      callback,
-    });
+    if (
+      !previewQueue.find((work) => {
+        return work.nbPath === nbAbsPath;
+      })
+    ) {
+      // Try to provide a title
+      previewQueue.push({
+        input,
+        nbPath: nbAbsPath,
+        title: title,
+        callback,
+        order,
+      });
+    }
   };
 
   const renderPreviews = async (output?: string, quiet?: boolean) => {
@@ -245,6 +255,7 @@ export const notebookPreviewer = (
           href: relative(inputDir, renderedNotebook[kHtmlPreview].hrefPath),
           supporting,
           resources,
+          order: work.order,
         };
         rendered[work.nbPath] = nbPreview;
         if (work.callback) {
@@ -255,6 +266,7 @@ export const notebookPreviewer = (
           href: pathWithForwardSlashes(join(nbDir, filename)),
           title: title || filename,
           filename,
+          order: work.order,
         };
         rendered[work.nbPath] = nbPreview;
         if (work.callback) {

src/format/html/format-html-notebook.ts

@@ -153,6 +153,7 @@ export async function emplaceNotebookPreviews(
           input,
           input,
           undefined, // title
+          undefined, // order
           (nbPreview) => {
             // If this is a cell _in_ a source notebook, it will not be parented
             // by an embed cell
@@ -175,7 +176,7 @@ export async function emplaceNotebookPreviews(
     }
 
     // For any notebooks explicitly provided, ensure they are rendered
-    if (typeof (notebookView) !== "boolean") {
+    if (typeof notebookView !== "boolean") {
       const nbs = Array.isArray(notebookView) ? notebookView : [notebookView];
       for (const nb of nbs) {
         // Filter out the root article notebook, since that was resolved
@@ -184,7 +185,7 @@ export async function emplaceNotebookPreviews(
           const nbAbsPath = isAbsolute(nb.notebook)
             ? nb.notebook
             : join(dirname(input), nb.notebook);
-          previewer.enQueuePreview(input, nbAbsPath, nb.title);
+          previewer.enQueuePreview(input, nbAbsPath, nb.title, nb.order);
         }
       }
     }
@@ -208,6 +209,7 @@ export async function emplaceNotebookPreviews(
           input,
           nbAbsPath(input, notebookPath),
           title === null ? undefined : title,
+          undefined, // order
           (nbPreview) => {
             // Add a decoration to this div node
             if (inline) {
@@ -221,8 +223,20 @@ export async function emplaceNotebookPreviews(
     // Render the notebook previews
     const previews = await previewer.renderPreviews(output, quiet);
 
+    // Get the preview notebooks in the correct order
+    const previewNotebooks = Object.values(previews).sort((a, b) => {
+      if (a.order !== undefined && b.order !== undefined) {
+        return a.order - b.order;
+      } else if (a.order !== undefined && b.order === undefined) {
+        return -1;
+      } else if (a.order === undefined && b.order !== undefined) {
+        return 1;
+      } else {
+        return a.title.localeCompare(b.title);
+      }
+    });
+
     // Emit global links to the notebooks
-    const previewNotebooks = Object.values(previews);
     if (global && previewNotebooks.length > 0) {
       const containerEl = doc.createElement("div");
       containerEl.classList.add("quarto-alternate-notebooks");

src/project/types/manuscript/manuscript.ts

@@ -157,12 +157,12 @@ export const manuscriptProjectType: ProjectType = {
     const article = computeProjectArticleFile(projectDir, manuscriptConfig);
 
     // Go through project inputs and use any of these as notebooks
-    const notebooks: Record<string, NotebookPreviewDescriptor> = {};
+    const notebooks: NotebookPreviewDescriptor[] = [];
 
     const explicitNotebooks = manuscriptConfig[kNotebooks];
     if (explicitNotebooks) {
-      resolveNotebookDescriptors(explicitNotebooks).forEach((nb) => {
-        notebooks[nb.notebook] = nb;
+      resolveNotebookDescriptors(explicitNotebooks, true).forEach((nb) => {
+        notebooks.push(nb);
       });
     } else {
       const inputNotebooks = inputs.files.map((input) => {
@@ -191,7 +191,7 @@ export const manuscriptProjectType: ProjectType = {
 
       if (inputNotebooks) {
         resolveNotebookDescriptors(inputNotebooks).forEach((nb) => {
-          notebooks[nb.notebook] = nb;
+          notebooks.push(nb);
         });
       }
     }
@@ -219,10 +219,17 @@ export const manuscriptProjectType: ProjectType = {
     // If there are computations in the main article, the add
     // it as a notebook to be rendered with computations intact
     if (await hasComputations(join(projectDir, article))) {
-      notebooks[article] = {
-        notebook: article,
-        title: language[kArticleNotebookLabel],
-      };
+      if (
+        !notebooks.find((nb) => {
+          return nb.notebook === article;
+        })
+      ) {
+        notebooks.unshift({
+          notebook: article,
+          title: language[kArticleNotebookLabel],
+          order: 9999,
+        });
+      }
       jatsNotebooks.unshift({
         input: join(projectDir, article),
         token: `nb-article`,
@@ -232,6 +239,7 @@ export const manuscriptProjectType: ProjectType = {
 
     // Determine the notebooks that are being declared explicitly in
     // in the manuscript configuration
+    /*
     if (manuscriptConfig.notebooks !== undefined) {
       const specifiedNotebooks = Array.isArray(manuscriptConfig.notebooks)
         ? manuscriptConfig.notebooks
@@ -240,6 +248,7 @@ export const manuscriptProjectType: ProjectType = {
         notebooks[nb.notebook] = nb;
       });
     }
+    */
 
     // Note JATS subarticles for the JATS format
     config[kQuartoInternal] = {
@@ -263,7 +272,7 @@ export const manuscriptProjectType: ProjectType = {
     const resolvedManuscriptOptions: ResolvedManuscriptConfig = {
       ...manuscriptConfig,
       article,
-      notebooks: Object.values(notebooks),
+      notebooks: notebooks,
       mecaFile: mecaFileOutput,
       [kEnvironmentFiles]: environmentFiles,
     };
@@ -505,8 +514,8 @@ export const manuscriptProjectType: ProjectType = {
       // If the user isn't explicitly providing a notebook list
       // then automatically create notebooks for the other items in
       // the project
-      const outputNbs: Record<string, NotebookPreviewDescriptor> = {};
       const notebooks = manuscriptConfig.notebooks || [];
+      const orderedNbs: NotebookPreviewDescriptor[] = [];
       for (const notebook of notebooks) {
         // Use the input to create a title for the notebook
         // if needed
@@ -521,12 +530,12 @@ export const manuscriptProjectType: ProjectType = {
           }
         };
 
-        outputNbs[notebook.notebook] = {
+        orderedNbs.push({
           ...notebook,
           title: notebook.title || await createTitle(),
-        };
+        });
       }
-      extras[kNotebooks] = Object.values(outputNbs);
+      extras[kNotebooks] = orderedNbs;
     } else if (isArticle && isLatexOutput(format.pandoc)) {
       if (isLatexOutput(format.pandoc)) {
         // By default, keep tex and clean things up ourselves
@@ -687,19 +696,25 @@ const hasComputations = async (file: string) => {
 
 const resolveNotebookDescriptor = (
   nb: string | NotebookPreviewDescriptor,
+  order?: number,
 ): NotebookPreviewDescriptor => {
   if (typeof nb === "string") {
-    nb = { notebook: nb };
+    nb = { notebook: nb, order };
   }
   return nb;
 };
 
 const resolveNotebookDescriptors = (
   nbs: Array<string | NotebookPreviewDescriptor>,
+  orderNotebooks = false,
 ) => {
   const resolvedNbs: NotebookPreviewDescriptor[] = [];
+  let order = 0;
   for (const nb of nbs) {
-    resolvedNbs.push(resolveNotebookDescriptor(nb));
+    resolvedNbs.push(
+      resolveNotebookDescriptor(nb, orderNotebooks ? order : undefined),
+    );
+    order++;
   }
   return resolvedNbs;
 };