Merge branch 'main' of github.com:quarto-dev/quarto-cli

Author: dragonstyle

design/TODO.txt

@@ -12,44 +12,23 @@ Markdown Serialization
 
 JJ: 
 
-- convert to/from text vs. ipynb representation
-    - notebook metadata: 
-        - dump into 'jupyter' front matter key on way to markdown
-        - 'jupyter' front matter goes into notebook metadata
-        -  'notebook', 'markdown' as convert targets, 
-        
-- dev server preview doesn't drive to last rendered
-- books-crossrefs.ts#127 - fixing up heading links not working properly 
 - TODO: measure lag at the beginning of project single file render
+- make sure that crossrefs are appropriately disabled for unumbered chapters
+- More opinionated <kbd>
+- can we make section-numbers work more sensibly with H2 (chapter-level). --top-level-division, --shift-heading-level
 
 
 CT:
 - search highlighting like is done in mastering-shiny
   (https://mastering-shiny.org/performance.html?q=plot#caching-plots)
   jumping between highlighted terms (via keyboard or affordance at right or top)
 
+- Better treatment for code blocks within tabs (just use a thin border, could
+  consider background color)
 
 
-books
-=====================================================================
-
-- make sure that crossrefs are appropriately disabled for unumbered chapters
-- More opinionated <kbd>
-
-- can we make section-numbers work more sensibly with H2 (chapter-level). --top-level-division, --shift-heading-level
-
-- footnotes: 
-    (1) do we have consistent behavior across formats
-    (2) can we provide options for per-chapter vs. global
 
 
-quarto-python dev workflow:
-
-```bash
-$ python3 -m venv .venv    
-$ source .venv/bin/activate
-$ pip install -e ./ 
-```
 
 TODO
 =====================================================================
@@ -78,6 +57,16 @@ TODO: convert to css grid for columns (allows for content floating and crossing
 
 
 
+
+quarto-python dev workflow:
+
+```bash
+$ python3 -m venv .venv    
+$ source .venv/bin/activate
+$ pip install -e ./ 
+```
+
+
 Installation/Compilation
 =====================================================================
 
@@ -107,6 +96,11 @@ JupyterLab
 
 - webshot equivalent for printed output
 
+
+- footnotes: 
+    (1) do we have consistent behavior across formats
+    (2) can we provide options for per-chapter vs. global
+
 - Bibliography per chapter
 
 - Glossaries (https://jupyterbook.org/content/content-blocks.html#glossaries)

src/command/convert/cmd.ts

@@ -26,7 +26,7 @@ export const convertCommand = new Command()
     "Convert between markdown and notebook representations of documents.",
   )
   .option(
-    "-t, --to <format:string>",
+    "-t, --to [format:string]",
     "Format to convert to (markdown or notebook)",
   )
   .option(
@@ -65,8 +65,10 @@ export const convertCommand = new Command()
       : kMarkdownFormat;
 
     // determine and validate target format
-    const targetFormat = options.to ||
-      (srcFormat === kNotebookFormat ? kMarkdownFormat : kNotebookFormat);
+    const targetFormat = options.to;
+    if (!targetFormat) {
+      throw new Error("Target format (--to) not specified");
+    }
     if (![kNotebookFormat, kMarkdownFormat].includes(targetFormat)) {
       throw new Error("Invalid target format: " + targetFormat);
     }
@@ -82,7 +84,7 @@ export const convertCommand = new Command()
 
     // perform conversion
     const converted = srcFormat === kNotebookFormat
-      ? convertNotebookToMarkdown(path)
+      ? convertNotebookToMarkdown(path, includeIds)
       : await convertMarkdownToNotebook(path, includeIds);
 
     // write output

src/command/convert/convert.ts

@@ -5,29 +5,165 @@
 *
 */
 
+import { stringify } from "encoding/yaml.ts";
+
+import {
+  partitionYamlFrontMatter,
+  readYamlFromMarkdown,
+} from "../../core/yaml.ts";
 import {
-  jupyterKernelspecFromFile,
+  jupyterAutoIdentifier,
+  JupyterCell,
+  JupyterCellOptions,
+  jupyterCellOptionsAsComment,
+  jupyterFromFile,
+  kCellId,
+  kCellLabel,
+  mdEnsureTrailingNewline,
+  mdFromContentCell,
+  mdFromRawCell,
+  partitionJupyterCellOptions,
   quartoMdToJupyter,
 } from "../../core/jupyter/jupyter.ts";
+import { Metadata } from "../../config/metadata.ts";
 
 export async function convertMarkdownToNotebook(
   file: string,
   includeIds: boolean,
 ) {
-  const [kernelspec, metadata] = await jupyterKernelspecFromFile(file);
-  const notebook = quartoMdToJupyter(
-    file,
-    kernelspec,
-    metadata,
-    includeIds,
-  );
+  const notebook = await quartoMdToJupyter(file, includeIds);
   return JSON.stringify(notebook, null, 2);
 }
 
-export function convertNotebookToMarkdown(file: string) {
-  // TODO:  when converting from notebook to markdown, we do carry any id we find into metadata, however if the
-  //        id matches the auto-converted label then we don't include id
-  //         (could be command line flags to eliminate ids)
+export function convertNotebookToMarkdown(file: string, includeIds: boolean) {
+  // read notebook & alias kernelspec
+  const notebook = jupyterFromFile(file);
+  const kernelspec = notebook.metadata.kernelspec;
+
+  // generate markdown
+  const md: string[] = [];
+
+  for (let i = 0; i < notebook.cells.length; i++) {
+    {
+      // alias cell
+      const cell = notebook.cells[i];
+
+      // write markdown
+      switch (cell.cell_type) {
+        case "markdown":
+          md.push(...mdFromContentCell(cell));
+          break;
+        case "raw":
+          md.push(...mdFromRawCell(cell));
+          break;
+        case "code":
+          md.push(...mdFromCodeCell(kernelspec.language, cell, includeIds));
+          break;
+        default:
+          throw new Error("Unexpected cell type " + cell.cell_type);
+      }
+    }
+  }
+
+  // join into source
+  const mdSource = md.join("");
+
+  // add jupyter kernelspec to front-matter
+  const partitioned = partitionYamlFrontMatter(mdSource);
+  if (partitioned?.yaml) {
+    const yaml = readYamlFromMarkdown(partitioned.yaml);
+    yaml.jupyter = notebook.metadata;
+    const yamlText = stringify(yaml, {
+      indent: 2,
+      sortKeys: false,
+      skipInvalid: true,
+    });
+    return `---\n${yamlText}---\n${partitioned.markdown}\n`;
+  } else {
+    return mdSource;
+  }
+}
+
+function mdFromCodeCell(
+  language: string,
+  cell: JupyterCell,
+  includeIds: boolean,
+) {
+  // redact if the cell has no source
+  if (!cell.source.length) {
+    return [];
+  }
+
+  // begin code cell
+  const md: string[] = ["```{" + language + "}\n"];
+
+  // partition
+  const { yaml, source } = partitionJupyterCellOptions(language, cell.source);
+  const options = yaml ? yaml as JupyterCellOptions : {};
+  console.log(options);
+
+  // handle id
+  if (cell.id) {
+    if (!includeIds) {
+      cell.id = undefined;
+    } else if (options[kCellLabel]) {
+      const label = String(options[kCellLabel]);
+      if (jupyterAutoIdentifier(label) === cell.id) {
+        cell.id = undefined;
+      }
+    }
+  }
+
+  // prepare the options for writing
+  let yamlOptions: Metadata = {};
+  if (cell.id) {
+    yamlOptions[kCellId] = cell.id;
+  }
+  yamlOptions = {
+    ...cell.metadata,
+    ...yaml,
+    ...yamlOptions,
+  };
+
+  // cell id first
+  if (yamlOptions[kCellId]) {
+    md.push(
+      ...jupyterCellOptionsAsComment(language, { id: yamlOptions[kCellId] }),
+    );
+    delete yamlOptions[kCellId];
+  }
+
+  // yaml
+  if (yaml) {
+    const yamlOutput: Metadata = {};
+    for (const key in yaml) {
+      const value = yamlOptions[key];
+      if (value !== undefined) {
+        yamlOutput[key] = value;
+        delete yamlOptions[key];
+      }
+    }
+    md.push(...jupyterCellOptionsAsComment(language, yamlOutput));
+  }
+
+  // metadata
+  const metadataOutput: Metadata = {};
+  for (const key in cell.metadata) {
+    const value = cell.metadata[key];
+    if (value !== undefined) {
+      metadataOutput[key] = value;
+      delete yamlOptions[key];
+    }
+  }
+  md.push(
+    ...jupyterCellOptionsAsComment(language, metadataOutput, { flowLevel: 1 }),
+  );
+
+  // write cell code
+  md.push(...mdEnsureTrailingNewline(source));
+
+  // end code cell
+  md.push("```\n");
 
-  return "";
+  return md;
 }

src/command/serve/watch.ts

@@ -66,6 +66,9 @@ export function watchProject(
 
   // lib dir
   const libDirConfig = project.config?.project[kProjectLibDir];
+  const libDirSource = libDirConfig
+    ? join(project.dir, libDirConfig)
+    : undefined;
   const libDir = libDirConfig ? join(outputDir, libDirConfig) : undefined;
 
   // if any of the paths are in the output dir (but not the lib dir) then return true
@@ -84,6 +87,10 @@ export function watchProject(
 
   // is this a resource file?
   const isResourceFile = (path: string) => {
+    // exclude libdir
+    if (libDirSource && path.startsWith(libDirSource)) {
+      return false;
+    }
     if (renderResult) {
       if (project.files.resources?.includes(path)) {
         return true;