Fix keep-md cleanup deleting the markdown output when output-file has an .html extension (#14671)

When a project pairs an html format with a markdown format and output-file
carries an .html extension (e.g. output-file: index.html, as nbdev sets on
every page for llms.txt workflows), the markdown twin's path (index.html.md)
coincides with the keep-md intermediate convention for the html format. The
html render's cleanup reclaimed that path as a stale intermediate and deleted
the freshly-written markdown output — a hard error at the output-move step in
website projects, a silent drop in default projects.

keep-md handling now never writes to or deletes a path a declared format owns.
This covers full multi-format renders, partial renders (quarto render --to html
must not delete a twin a previous full render produced, since outputs live in
place in default projects), and keep-md: true (the declared output wins; the
intermediate write is skipped with a warning).

Closes #14669.

Author: cscheid

news/changelog-1.10.md

@@ -115,3 +115,4 @@ All changes included in 1.10:
 - ([#14582](https://github.com/quarto-dev/quarto-cli/issues/14582)): Fix format detection for extension formats (e.g. `acm-pdf`) in project preview, manuscript notebooks, MECA bundles, and website format ordering.
 - ([#14583](https://github.com/quarto-dev/quarto-cli/issues/14583)): Fix a shortcode used as an image source (e.g. `![]({{< meta logo >}})`) getting the `default-image-extension` appended, producing a doubled extension once the shortcode resolves.
 - ([#14595](https://github.com/quarto-dev/quarto-cli/issues/14595)): Fix reload preview in code-server environment
+- ([#14669](https://github.com/quarto-dev/quarto-cli/issues/14669)): Fix markdown output being deleted when `output-file` has an `.html` extension and an html format is paired with a markdown format.

src/command/render/render-files.ts

@@ -62,7 +62,7 @@ import {
   RenderFlags,
   RenderOptions,
 } from "./types.ts";
-import { error, info } from "../../deno_ral/log.ts";
+import { error, info, warning } from "../../deno_ral/log.ts";
 import * as ld from "../../core/lodash.ts";
 import { basename, dirname, join, relative } from "../../deno_ral/path.ts";
 import { Format } from "../../config/types.ts";
@@ -71,6 +71,8 @@ import {
   inputFilesDir,
   isServerShiny,
   isServerShinyKnitr,
+  keepMdCollidesWithFormatOutput,
+  projectedOutputFile,
 } from "../../core/render.ts";
 import {
   normalizePath,
@@ -460,6 +462,20 @@ async function renderFileInternal(
       files,
       options,
     );
+
+    // let each context know the projected outputs of every declared format,
+    // including formats not in this render (e.g. quarto render --to html):
+    // keep-md intermediate handling must not write to or delete a path that
+    // a format owns (e.g. output-file: index.html plus a markdown format
+    // yields index.html.md, which is also the conventional keep-md location
+    // for the html format) (#14669)
+    const formatOutputs = Object.values(contexts)
+      .map((context) =>
+        projectedOutputFile(context.target.input, context.format)
+      );
+    for (const context of Object.values(contexts)) {
+      context.siblingFormatOutputs = formatOutputs;
+    }
   } catch (e) {
     // bad YAML can cause failure before validation. We
     // reconstruct the context as best we can and try to validate.
@@ -670,7 +686,23 @@ async function renderFileInternal(
           // keep md if requested
           const keepMd = executionEngineKeepMd(context);
           if (keepMd && context.format.execute[kKeepMd]) {
-            Deno.writeTextFileSync(keepMd, executeResult.markdown.value);
+            if (
+              keepMdCollidesWithFormatOutput(
+                keepMd,
+                context.siblingFormatOutputs,
+              )
+            ) {
+              warning(
+                `${
+                  basename(context.target.input)
+                }: not saving the keep-md intermediate because its ` +
+                  `conventional location (${
+                    basename(keepMd)
+                  }) is the output file of another format`,
+              );
+            } else {
+              Deno.writeTextFileSync(keepMd, executeResult.markdown.value);
+            }
           }
 
           // now get "unmapped" execute result back to send to pandoc

src/command/render/render.ts

@@ -12,7 +12,10 @@ import { Document, parseHtml } from "../../core/deno-dom.ts";
 
 import { mergeConfigs } from "../../core/config.ts";
 import { resourcePath } from "../../core/resources.ts";
-import { inputFilesDir } from "../../core/render.ts";
+import {
+  inputFilesDir,
+  keepMdCollidesWithFormatOutput,
+} from "../../core/render.ts";
 import {
   normalizePath,
   pathWithForwardSlashes,
@@ -374,14 +377,23 @@ export async function renderPandoc(
       }
 
       if (cleanup !== false) {
+        // the conventional keep-md location can coincide with the declared
+        // output of another format (e.g. output-file: index.html plus a
+        // markdown format yields index.html.md) -- never clean up a path
+        // that a format owns (#14669)
+        const keepMd = executionEngineKeepMd(context);
+        const keepMdIsFormatOutput = keepMdCollidesWithFormatOutput(
+          keepMd,
+          context.siblingFormatOutputs,
+        );
         withTiming("render-cleanup", () =>
           renderCleanup(
             context.target.input,
             finalOutput!,
             format,
             file.context.project,
             cleanupSelfContained,
-            executionEngineKeepMd(context),
+            keepMdIsFormatOutput ? undefined : keepMd,
           ));
       }
 

src/command/render/types.ts

@@ -61,6 +61,9 @@ export interface RenderContext {
   libDir: string;
   project: ProjectContext;
   active: boolean;
+  // projected output paths of the input's other formats; keep-md intermediate
+  // handling must not write to or delete paths a format owns (#14669)
+  siblingFormatOutputs?: string[];
 }
 
 export interface RunPandocResult {

src/core/render.ts

@@ -7,8 +7,8 @@
 import { kOutputExt, kOutputFile, kServer } from "../config/constants.ts";
 import { Format, Metadata } from "../config/types.ts";
 import { kJupyterEngine, kKnitrEngine } from "../execute/types.ts";
-import { dirAndStem } from "./path.ts";
-import { extname } from "../deno_ral/path.ts";
+import { dirAndStem, pathsEqual } from "./path.ts";
+import { dirname, extname, join } from "../deno_ral/path.ts";
 
 export function inputFilesDir(input: string) {
   const [_, stem] = dirAndStem(input);
@@ -44,6 +44,32 @@ export function isServerShinyKnitr(
   return isServerShiny(format) && engine === kKnitrEngine;
 }
 
+// the path a format's rendered output is written to before any project
+// output-dir relocation: an explicit output-file (with the format's extension
+// appended by formatOutputFile when it differs), else <input-stem>.<output-ext>.
+// used to detect collisions between declared outputs and the keep-md
+// intermediate naming convention (#14669); doesn't cover recipe special cases
+// (--output flag, md-to-md rename, stdout) which can't produce colliding names
+export function projectedOutputFile(input: string, format: Format): string {
+  const outputFile = formatOutputFile(format);
+  if (outputFile) {
+    return join(dirname(input), outputFile);
+  }
+  const [dir, stem] = dirAndStem(input);
+  return join(dir, `${stem}.${format.render[kOutputExt] || "html"}`);
+}
+
+// true when the keep-md intermediate location is a path another declared
+// format owns, so it must not be written to or cleaned up (#14669)
+export function keepMdCollidesWithFormatOutput(
+  keepMd: string | undefined,
+  siblingFormatOutputs: string[] | undefined,
+): boolean {
+  return keepMd !== undefined &&
+    (siblingFormatOutputs?.some((output) => pathsEqual(output, keepMd)) ??
+      false);
+}
+
 export function formatOutputFile(format: Format) {
   let outputFile = format.pandoc[kOutputFile];
   if (outputFile) {

tests/docs/output-file-collision/default/.gitignore

@@ -0,0 +1,7 @@
+/.quarto/
+/index.html
+/index.html.md
+/index.commonmark.md
+/index_files/
+/site_libs/
+**/*.quarto_ipynb

tests/docs/output-file-collision/default/_quarto.yml

@@ -0,0 +1,6 @@
+project:
+  type: default
+
+format:
+  html: default
+  commonmark: default

tests/docs/output-file-collision/default/index.qmd

@@ -0,0 +1,6 @@
+---
+title: Home
+output-file: index.html
+---
+
+Hello.

tests/docs/output-file-collision/keepmd/.gitignore

@@ -0,0 +1,6 @@
+/.quarto/
+/_site/
+/site_libs/
+/index.html
+/index.commonmark.md
+**/*.quarto_ipynb

tests/docs/output-file-collision/keepmd/_quarto.yml

@@ -0,0 +1,9 @@
+project:
+  type: website
+
+format:
+  html: default
+  commonmark: default
+
+execute:
+  keep-md: true