From 431b1c054c4c71d98194bfe48ee9ad9123df01fb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 19 May 2026 14:14:48 +0000
Subject: [PATCH] Fix: raise on config.yml parse errors instead of silently
 returning empty dict

A YAML parse error in config.yml (e.g. a stray tab character) caused
read_config to swallow the exception and return {}, disabling categories
and producing a broken nav.yml with no variants fields and wrong filenames.
read_config now raises ClickException on both OSError and YAMLError.

Documented in docs/knownbugs.md and docs/unreleased.md.

https://claude.ai/code/session_01Xs5GyREFhjWxhS1UhW2wA8
---
 docs/knownbugs.md  | 15 +++++++++++++++
 docs/unreleased.md |  8 ++++++++
 mdcms.py           |  7 +++++--
 3 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 docs/knownbugs.md

diff --git a/docs/knownbugs.md b/docs/knownbugs.md
new file mode 100644
index 0000000..5999aa0
--- /dev/null
+++ b/docs/knownbugs.md
@@ -0,0 +1,15 @@
+# Known bugs
+
+Bugs that have been identified but not yet fixed. Fixed bugs are moved to the release notes.
+
+---
+
+## Fixed in development (not yet released)
+
+### `config.yml` YAML parse errors were silently swallowed
+
+**Symptom:** A malformed `config.yml` (e.g. a stray tab character, which YAML forbids as a token starter) caused `read_config` to catch the `YAMLError` and return an empty dict. The build would proceed with no config — categories disabled, no default category code — producing a `nav.yml` that omitted `variants` fields and listed category variant files (e.g. `page.current.md`) as plain pages. Pages with category variants would not appear in the sidebar.
+
+**Root cause:** `read_config` caught `(OSError, yaml.YAMLError)` in a single block and silently returned `{}` on any error.
+
+**Fix:** `read_config` now raises `click.ClickException` on both `OSError` and `yaml.YAMLError`, aborting the build with a descriptive error message instead of continuing with an empty config.
diff --git a/docs/unreleased.md b/docs/unreleased.md
index 3068e82..7cc5389 100644
--- a/docs/unreleased.md
+++ b/docs/unreleased.md
@@ -40,3 +40,11 @@ After rebuilding a site with `mdcms build`, affected post entries in `nav.yml` g
 In `search.json`, these entries carry `"category": null` instead of the default category code. This is what tells the renderer to include them universally.
 
 A rebuild is required for existing sites to pick up the change.
+
+---
+
+## Fix: `config.yml` YAML parse errors now abort the build with a clear message
+
+A malformed `config.yml` (e.g. a stray tab character, which YAML forbids as a token starter) previously caused `read_config` to silently return an empty dict. The build would proceed with no config — categories disabled, no default category code — producing a broken `nav.yml` with wrong filenames and missing `variants` fields, so category-variant pages would not appear in the sidebar.
+
+`read_config` now raises `ClickException` on both `OSError` and `yaml.YAMLError`, aborting the build with a descriptive error message instead of continuing silently with an empty config.
diff --git a/mdcms.py b/mdcms.py
index 10229f0..9196751 100644
--- a/mdcms.py
+++ b/mdcms.py
@@ -113,9 +113,12 @@ def read_config(site_path: Path) -> dict:
         return {}
     try:
         text = config_file.read_text(encoding="utf-8")
+    except OSError as e:
+        raise click.ClickException(f"Could not read config.yml: {e}")
+    try:
         return yaml.safe_load(text) or {}
-    except (OSError, yaml.YAMLError):
-        return {}
+    except yaml.YAMLError as e:
+        raise click.ClickException(f"config.yml is not valid YAML: {e}")
 
 
 def get_category_info(cfg: dict) -> dict: