Build versioned & unversioned docs at the same path depth level - #325
Merged
Conversation
Historical versions rewrote their Quarto configuration without the generated-file header. Readers could no longer tell that Great Docs owned the file, and cleanup could not safely identify build output. Write the same header for every version and recognise build directories only when their Quarto configuration contains the Great Docs marker.
Versioned builds previously nested Quarto projects under an extra build directory. Relative paths that leave the staged documentation tree therefore resolved differently from non-versioned builds. Render the latest version in great-docs/ and historical versions in sibling directories. Copy historical trees before pruning the latest tree, and report unrecognised sibling directories instead of deleting them. A single-version build creates no sibling directory. Fixes posit-dev#319
Historical version projects moved next to great-docs/, but cache collection still searched the old nested layout. Quarto therefore re-executed code for every historical version on every build. Collect caches from the latest build directory and each marked historical sibling before merging them into the project cache. Refs posit-dev#319
Historical versions now render beside great-docs/ in directories named from the documentation directory and version tag. Replace the ignore rule for the retired nested build root with a pattern that covers the new sibling directories. Refs posit-dev#319
MCP commands still searched the retired nested directory and exposed a build log that Great Docs never created. They therefore missed previews, cleanup targets, status details, and historical output. Find current and historical build directories in their new locations. Clean only marked historical directories, and explain that Great Docs prints build logs but does not save them. Refs posit-dev#319
Quarto resolves an include outside the documentation tree from the staged page location. If a version project is nested at a different depth, the same include path resolves to a different file or no file. Assert that every version stages the page at a depth where the include resolves to the original project file. Refs posit-dev#319
Describe where Great Docs stores the latest version, historical versions, assembled site, and API cache. Explain why every Quarto project remains at the same depth and why custom includes should not depend on staged page locations. Document the generated ignore entries and the safeguards that distinguish build output from user-owned directories. Refs posit-dev#319
Historical freeze caches replaced whole sections, so one version could erase cached pages from another. The generated ignore rule matched nested project directories, and lint scanned staged page copies. Cleanup also removed previous version output before reporting a collision with an unmarked directory, while build-directory searches handled symlinks inconsistently. Merge cache files individually and give the latest version precedence. Anchor the historical ignore rule to the project root, exclude top-level build copies from linting, reject symlinked build directories consistently, and validate collisions before cleanup. Document that only versions selected for the current build are recreated. Refs posit-dev#319
Great Docs generated great-docs/ without a leading slash, so Git ignored directories with that name anywhere in the project. Substring checks could also mistake a negated nested path for the main build rule. Write /great-docs/, compare complete lines, and migrate the old rule after the next approved update. Preserve similar patterns and leave the file unchanged when the user declines. Refs kata 0545
Page completion returned every .qmd file in the project, including staged copies in current and historical build directories. Agents therefore saw duplicate, disposable pages and could select paths that the next build would overwrite. Use the same top-level build-path classification for linting and page completion. Keep nested project directories with similar names in the source listing. Refs kata nxaj
Require the complete generated header before treating a same-level `great-docs-<tag>/` directory as build output. This keeps linting and page completion active for similarly named user directories. It also prevents uninstall and version cleanup from deleting those directories. Reject symlinked historical build targets before preprocessing. This prevents version builds from writing through a link.
has2k1
changed the title
rich-iannone
self-requested a review
August 19, 2026 20:53
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR moves versioned builds to a same-level directory layout so that every version's Quarto project sits exactly one level below the project root, and hardens the surrounding tooling against deleting or duplicating user-owned directories.
fixes #319