From 58c3f5022ab4c1506a4e16a664174dbc33878900 Mon Sep 17 00:00:00 2001
From: peter <petrel.harp@gmail.com>
Date: Thu, 15 Jan 2026 21:39:28 -0800
Subject: [PATCH] clarify deletion behavior of output-dir (closes #13896)

---
 src/command/render/cmd.ts        | 4 ++--
 src/resources/schema/project.yml | 6 +++++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/command/render/cmd.ts b/src/command/render/cmd.ts
index 0c31b66a0ac..bd4b86181ef 100644
--- a/src/command/render/cmd.ts
+++ b/src/command/render/cmd.ts
@@ -37,7 +37,7 @@ export const renderCommand = new Command()
   )
   .option(
     "--output-dir",
-    "Write output to DIR (path is input/project relative)",
+    "Write output to DIR, which is first deleted (path is input/project relative)",
   )
   .option(
     "-M, --metadata",
@@ -89,7 +89,7 @@ export const renderCommand = new Command()
   )
   .option(
     "--no-clean",
-    "Do not clean project output-dir prior to render",
+    "Do not delete output-dir prior to render",
   )
   .option(
     "--debug",
diff --git a/src/resources/schema/project.yml b/src/resources/schema/project.yml
index 311a2d360c6..9f573d87090 100644
--- a/src/resources/schema/project.yml
+++ b/src/resources/schema/project.yml
@@ -24,7 +24,11 @@
               - `project`: Use the root directory of the project.
         output-dir:
           path:
-            description: "Output directory"
+            description:
+              short: "Output directory"
+              long: >
+              The directory in which all outputs are placed. If a directory with this name
+              already exists, it will be deleted and replaced with a new directory.
         lib-dir:
           path:
             description: "HTML library (JS/CSS/etc.) directory"