From e7591c61e706c2a95341e9bb0857f81be11355aa Mon Sep 17 00:00:00 2001
From: Muhammad Asad <140322913+Masad791@users.noreply.github.com>
Date: Tue, 13 Oct 2026 08:45:13 +0500
Subject: [PATCH] Warn and ignore a brand file that holds only comments

A commented-out `_brand.yml` is useful as a template, but it parses to no
YAML value, so brand validation failed with `YAML value is missing` and the
render stopped. Both brand loaders now check for an empty YAML value first,
warn once, and treat the file as absent. Invalid YAML still goes through
validation so its error is reported as before.

Fixes #14891
---
 news/changelog-1.11.md                        |  1 +
 src/project/project-shared.ts                 | 30 +++++++++++++++++--
 .../2026/10/13/issue-14891/_brand.yml         |  5 ++++
 .../2026/10/13/issue-14891/index.qmd          | 13 ++++++++
 4 files changed, 46 insertions(+), 3 deletions(-)
 create mode 100644 tests/docs/smoke-all/2026/10/13/issue-14891/_brand.yml
 create mode 100644 tests/docs/smoke-all/2026/10/13/issue-14891/index.qmd

diff --git a/news/changelog-1.11.md b/news/changelog-1.11.md
index 839d7ca3606..e9ddf08cf0d 100644
--- a/news/changelog-1.11.md
+++ b/news/changelog-1.11.md
@@ -39,6 +39,7 @@ All changes included in 1.11:
 ### All Formats
 
 - ([#14772](https://github.com/quarto-dev/quarto-cli/issues/14772)): Custom `language` keys now reach templates through `$quarto.language.<key>$`. A key that Quarto does not ship passed schema validation and was merged over the defaults, then discarded before templates saw it, so it expanded to an empty string with no warning. (author: @mcanouil)
+- ([#14891](https://github.com/quarto-dev/quarto-cli/issues/14891)): A brand file that holds only comments, such as a commented-out `_brand.yml` template, now prints a warning and is ignored instead of stopping the render with `YAML value is missing`.
 
 ### `dashboard`
 
diff --git a/src/project/project-shared.ts b/src/project/project-shared.ts
index 1eac8e6cc0e..c6c3acfa621 100644
--- a/src/project/project-shared.ts
+++ b/src/project/project-shared.ts
@@ -5,6 +5,7 @@
  */
 
 import { existsSync, safeRemoveSync } from "../deno_ral/fs.ts";
+import { warnOnce } from "../core/log.ts";
 import {
   dirname,
   isAbsolute,
@@ -553,7 +554,26 @@ export async function projectResolveBrand(
   project: ProjectContext,
   fileName?: string,
 ): Promise<LightDarkBrandDarkFlag | undefined> {
-  async function loadSingleBrand(brandPath: string): Promise<Brand> {
+  // A brand file holding only comments (e.g. a commented-out template) has no
+  // YAML value and would fail validation, so warn and treat it as absent.
+  function isEmptyBrandFile(brandPath: string): boolean {
+    let empty = false;
+    try {
+      empty = parse(Deno.readTextFileSync(brandPath)) == null;
+    } catch {
+      // invalid YAML: let validation report it
+    }
+    if (empty) {
+      warnOnce(`Brand file ${brandPath} has no content and will be ignored.`);
+    }
+    return empty;
+  }
+  async function loadSingleBrand(
+    brandPath: string,
+  ): Promise<Brand | undefined> {
+    if (isEmptyBrandFile(brandPath)) {
+      return undefined;
+    }
     const brand = await readAndValidateYamlFromFile(
       brandPath,
       refSchema("brand-single", "Format-independent brand configuration."),
@@ -563,7 +583,10 @@ export async function projectResolveBrand(
   }
   async function loadUnifiedBrand(
     brandPath: string,
-  ): Promise<LightDarkBrandDarkFlag> {
+  ): Promise<LightDarkBrandDarkFlag | undefined> {
+    if (isEmptyBrandFile(brandPath)) {
+      return undefined;
+    }
     const brand = await readAndValidateYamlFromFile(
       brandPath,
       refSchema("brand-unified", "Format-independent brand configuration."),
@@ -662,7 +685,8 @@ export async function projectResolveBrand(
       if (!existsSync(brandPath)) {
         continue;
       }
-      project.brandCache.brand = await loadUnifiedBrand(brandPath);
+      project.brandCache.brand = (await loadUnifiedBrand(brandPath)) ??
+        project.brandCache.brand;
     }
     return project.brandCache.brand;
   } else {
diff --git a/tests/docs/smoke-all/2026/10/13/issue-14891/_brand.yml b/tests/docs/smoke-all/2026/10/13/issue-14891/_brand.yml
new file mode 100644
index 00000000000..0b2bb550960
--- /dev/null
+++ b/tests/docs/smoke-all/2026/10/13/issue-14891/_brand.yml
@@ -0,0 +1,5 @@
+# A brand file that only holds comments, e.g. a commented-out template.
+# color:
+#   primary: "#447099"
+# typography:
+#   base: Inter
diff --git a/tests/docs/smoke-all/2026/10/13/issue-14891/index.qmd b/tests/docs/smoke-all/2026/10/13/issue-14891/index.qmd
new file mode 100644
index 00000000000..3b4eca0cae0
--- /dev/null
+++ b/tests/docs/smoke-all/2026/10/13/issue-14891/index.qmd
@@ -0,0 +1,13 @@
+---
+title: "Comment-only _brand.yml"
+format: html
+_quarto:
+  tests:
+    html:
+      noErrors: true
+      printsMessage:
+        level: WARN
+        regex: '_brand\.yml has no content and will be ignored'
+---
+
+A `_brand.yml` holding only comments should warn and be ignored, not stop the render.