Global System Configurations

The Universal Document Engine uses a global configuration file — conventionally named ude_global_config.json (the engine also recognizes the legacy name ude_global.json) — to control system-wide behaviors that apply to every target compilation pipeline: logging verbosity, the on-disk build cache location, Doxygen discovery, and documentation-coverage gating.

---

📋 File Schema Overview

The global config is auto-discovered by walking up the directory tree from the doc-config's own directory (unless an explicit --global-config path is passed on the CLI). It is parsed into a strictly-typed GlobalConfig model with extra="ignore" semantics — unknown keys are silently dropped, not rejected — so a typo in a key name will not raise an error, it will simply have no effect.

IMPORTANT

There is no free-form logging or caching block. The real schema is a flat set of top-level keys — see below.

The real, validated fields of GlobalConfig are:

Key	Type	Default	Purpose
doxygen_path	string | null	null	Directory containing the Doxygen executable. If set, it is resolved to an absolute path and prepended to the process PATH environment variable — this is the only place in the engine that touches an environment variable.
log_level	string	"WARNING"	Passed straight to Python's logging module. An invalid value silently falls back to WARNING rather than raising.
log_file	string | null	null	If set, log output is also written to this file, in addition to always going to stderr. If the file can't be opened, this only logs a warning — it never crashes the build.
cache_root_dir	string | null	null	Root directory for the on-disk build cache: L1 (collected Doxygen XML) and L2 (rendered output). Resolved to an absolute path relative to the global config file's own directory.
global_templates_dir	string | null	null	Root directory for shared global templates (e.g. a shared Doxyfile tier). Resolved the same way as cache_root_dir.
error_policy	string	"fail-fast"	Pipeline error handling policy. The other value seen in real-world configs is "continue-on-error".
translation_service	string | null	null	Optional identifier of a configured translation backend.
coverage_mode	"allow-undocumented" | "reject-undocumented"	"allow-undocumented"	Documentation coverage gate mode.
coverage_threshold	float (0.0–1.0)	1.0	Minimum fraction of documented entities required to pass the coverage gate.

CAUTION

coverage_threshold is a fraction, not a percentage. 0.98 means 98%. This is easy to confuse with the ude audit CLI command's --threshold flag, which takes a human-friendly percentage (e.g. 98) and divides it by 100 at the CLI boundary before it ever reaches this config. If you copy a number from one to the other without converting, your gate will be silently wrong (e.g. passing 98 here would require 9800% coverage — impossible — so the gate would always fail).

---

🪦 The Removed sidebar_structures_dir Key

If a global config JSON still contains a sidebar_structures_dir key — left over from an older config generation — loading it raises a fatal, explicit error:

UdeException: sidebar_structures_dir is removed as of [GAP-32-Debt-2]; folder taxonomy is now sourced from sidebar.toml [groups].

IMPORTANT

Migration trap: this is one of the few keys the engine actively rejects rather than silently ignoring, specifically to stop a stale config from producing a build that runs but silently drops the intended sidebar taxonomy. If you hit this exception, remove sidebar_structures_dir from the global config and move the equivalent structure into a project's sidebar.toml [groups] table instead (see Target Settings for the [groups] schema).

---

📂 A Real Example, Corrected

Real-world global configs in this repository (e.g. ude_projects/ude_global_config.json) look like this:

{
    "error_policy": "continue-on-error",
    "logging": {"level": "INFO", "file": "../ude_system.log"},
    "doxygen_binary": "doxygen",
    "stylesheet_dir": "../engine/ude/templates/css/default",
    "output_base_dir": "../ude_output",
    "api_version": "27.6"
}

Of these six keys, only error_policy maps onto an actual GlobalConfig field. The rest split into two very different categories:

• stylesheet_dir, output_base_dir, api_version are real and meaningful — but not because GlobalConfig validates them. The orchestrator reads these directly off the merged config dictionary (the result of the global → SDK → doc-config cascade described in Target Settings), not off the typed GlobalConfig object. stylesheet_dir picks the CSS asset source for HTML/Legacy-HTML output; output_base_dir pairs with a doc-config's output_subdir to build the final output path; api_version is a template-interpolation variable used by renderers, defaulting to "27.6" if it's absent anywhere in the merged config.
• logging (nested) and doxygen_binary are inert — they look like reasonable names but don't match any real GlobalConfig field (which is log_level/log_file/doxygen_path, flat, not nested). Because of extra="ignore", these are silently dropped at load time with no warning.

The corrected, canonical form of the same intent, expressed in fields GlobalConfig actually validates:

{
    "doxygen_path": null,
    "log_level": "INFO",
    "log_file": "../ude_system.log",
    "cache_root_dir": "../.ude_cache",
    "error_policy": "continue-on-error",
    "coverage_mode": "allow-undocumented",
    "coverage_threshold": 1.0
}

TIP

stylesheet_dir, output_base_dir, and api_version remain perfectly valid to set in this same file (or in an SDK-level/doc-level config instead) — just be aware they're read from the merged config dict by the orchestrator's rendering code, not validated by GlobalConfig. Most of what the orchestrator actually consumes is an untyped dict; GlobalConfig only covers the subset of keys listed in the table above.

---

🧭 Where This Fits

For the full 3-tier cascade that combines this global config with an SDK/product config and a per-target doc config — including how lists and dicts merge differently, and how the sidebar.toml [groups] taxonomy has its own nested 3-tier cascade — see Target Settings.