Build versioned & unversioned docs at the same path depth level

.gitignore

@@ -145,15 +145,12 @@ __marimo__/
 !ROADMAP.md
 
 # Great Docs build directory (ephemeral, do not commit)
-great-docs/
-_great_docs_build/
+/great-docs/
+/great-docs-*/
 .great-docs-build/
 .great-docs-cache/
 .great-docs/
 
-# But keep the skills/great-docs/ directory (Agent Skills, not a build artifact)
-!skills/great-docs/
-
 # Build artifacts that may land at repo root (e.g. from direct Builder calls)
 /objects.json
 /reference/

great_docs/_lint.py

@@ -6,7 +6,7 @@
 from pathlib import Path
 
 from ._builtin.directives import DIRECTIVES
-from ._utils import parse_seealso
+from ._utils import is_in_great_docs_build_dir, parse_seealso
 
 
 @dataclass
@@ -621,13 +621,16 @@ def _check_stale_versions(project_root: Path, result: LintResult) -> None:
         re.MULTILINE,
     )
 
-    # Collect .qmd files (skip _site, _extensions, build dirs, hidden dirs)
+    # Ignore generated build copies at the project root. Nested directories
+    # with similar names remain part of the user's source tree.
     qmd_files = []
     for qmd in project_root.rglob("*.qmd"):
         rel = qmd.relative_to(project_root)
         parts = rel.parts
         if any(p.startswith("_") or p.startswith(".") for p in parts):
             continue
+        if is_in_great_docs_build_dir(parts, project_root):
+            continue
         qmd_files.append(qmd)
 
     for qmd_file in sorted(qmd_files):

great_docs/_utils.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Sequence
+from pathlib import Path
 
 _SEEALSO_RE = re.compile(
     r"^[^\S\r\n]*%seealso[^\S\r\n]+(.+?)[^\S\r\n]*$",
@@ -76,3 +78,68 @@ def parse_seealso(docstring: str) -> list[tuple[str, str]]:
             if name:
                 entries.append((name, desc.strip()))
     return entries
+
+
+QUARTO_YML_HEADER = (
+    "# Generated by Great Docs - Do not modify this file by hand.\n"
+    "# Configure settings in great-docs.yml instead.\n\n"
+)
+
+
+def is_great_docs_build_dir(path: Path) -> bool:
+    """
+    Identify a Great Docs-generated Quarto project directory
+
+    The directory must contain a readable UTF-8 `_quarto.yml` that begins with
+    the complete generated-file header. The exact match prevents build cleanup
+    from treating user directories as generated output.
+
+    Parameters
+    ----------
+    path
+        Directory to inspect.
+
+    Returns
+    -------
+    Whether the directory contains a Great Docs-generated `_quarto.yml`.
+    """
+    try:
+        with (path / "_quarto.yml").open(encoding="utf-8") as quarto_yml:
+            header = quarto_yml.read(len(QUARTO_YML_HEADER))
+    except (OSError, UnicodeDecodeError):
+        return False
+    return header == QUARTO_YML_HEADER
+
+
+def is_in_great_docs_build_dir(parts: Sequence[str], project_root: Path) -> bool:
+    """
+    Identify a project-relative path within Great Docs build output
+
+    Every path below the root `great-docs/` directory belongs to the current
+    build. A path below a root `great-docs-<tag>/` directory belongs to a
+    historical build only when that directory is not a symlink and contains
+    the complete generated-file header. Similar names elsewhere remain source
+    paths.
+
+    Parameters
+    ----------
+    parts
+        Path components relative to `project_root`.
+    project_root
+        Project root used to inspect historical build directories.
+
+    Returns
+    -------
+    Whether the path belongs to current or historical build output.
+    """
+    if not parts:
+        return False
+
+    name = parts[0]
+    if name == "great-docs":
+        return True
+    if not name.startswith("great-docs-"):
+        return False
+
+    candidate = project_root / name
+    return candidate.is_dir() and not candidate.is_symlink() and is_great_docs_build_dir(candidate)