Conversation
has2k1
force-pushed
the
implement-docs-layout
branch
from
September 17, 2026 13:05
5ac5560 to
71f6760
Compare
has2k1
changed the title
has2k1
force-pushed
the
implement-docs-layout
branch
from
September 17, 2026 15:24
71f6760 to
fa4431d
Compare
Keep generated Quarto projects separate from documentation inputs and package sources. Rebase shared assets and page links, preserve guide ordering and section URLs, and update build-path consumers.
Copy reference-style images and multiline HTML assets, preserve URL escaping, and resolve blended-homepage links against their final destination. Keep local agent guidance ignored.
Keep version build names and Git refs distinct from published URLs. Normalise numeric v-prefixed URLs, reject full-list collisions before building, and preserve local outputs while assembling deployment sites. Persist freeze caches beside the selected configuration and verify generated output ownership before cleanup or uninstall.
Keep package-root traversal for ambiguity and stale-version checks while excluding generated output from the selected layout. Include the selected documentation directory, shared sections, and the fallback root README.
Add optional configuration selection to CLI and MCP commands. Initialise new projects under docs, retain existing layouts and explicit output overrides, and resolve remote selections within their checkout.
Expose optional resource URI selection for custom and ambiguous layouts. Quote preview commands so paths containing spaces remain valid shell arguments.
Preserve configuration formatting and static reference targets while proposing source moves, cache recovery, and scoped output ignores. Report conflicts and unsupported inputs before mutation, and fingerprint retained files and moved directory inventories for later revalidation.
Distinguish directory hierarchy in source fingerprints and reject files that obstruct destination parents. Preserve generated API page links without requiring repository source files, while retaining missing-asset checks.
Recheck reviewed inputs, preserve edited originals, and record operation intent before changing files. Use exclusive moves and restore only unchanged migration results after handled failures. Retain interrupted transactions for manual inspection and block further migrations until recovery is resolved.
Limit completed and rolled-back transactions to journal cleanup instructions. Omit reversal commands for operations that never started or were already undone. Provide PowerShell recovery commands on Windows with literal quoted paths and operations that refuse existing destinations.
Check pending recovery before selecting configuration and apply the same reviewed proposal after confirmation. Preserve custom selections, reject conflicts unattended, and report usable build commands. Recommend migration once per root-layout build or preview session, including versioned builds and watch sessions.
Keep README-backed homepage links valid during migration and remove pruned API pages from historical version maps. Verify all layouts with real repeated Quarto builds, Git-tag introspection, freeze reuse, and published navigation.
Update guides, recipes, CLI help, workflow templates, and packaged agent references for docs/great-docs.yml, config-relative sources, nested Quarto projects, and docs/_site deployment. Preserve the repository's own source layout and live freeze example.
Preserve caches and historical builds when preflight fails. Refuse cache migrations that change ignore policy, and revalidate external policy inputs. Record authorised SEO additions without claiming unrelated deployment files.
Refuse ignored destinations for tracked caches and revalidate both normal and split indexes. Reject parent traversal before normalising explicit cache paths, then remove only the validated path.
Exercise current README asset staging and resolved timing output. Mark intended generated projects without bypassing ownership checks, use consistent single-version mocks, and preserve explicit root configuration coverage.
Teach the migration's reference scanner the same two rules the real build applies: it renames a content directory for publishing and, unless explicit ordering is configured, strips numeric prefixes from filenames. Add ContentDirectory and _denormalize so rewrite_document stops reporting broken or unresolved references for links that already resolve correctly once a build applies those rules. Wiring the caller (analyse.py) to supply real content directories follows in the next commit.
Move the D2, interlinks, and snapshot caches into the destination so migrated builds reuse their existing data offline. Document the resolved snapshot location and the fallback used when no cache directory is configured.
Extend migration coverage to include the interlinks cache alongside D2 and snapshots. Add version-build coverage to confirm that stale CLI pages are pruned from a snapshot in the configured cache.
Resolve missing-package paths inside the fixture tree so layout discovery cannot escape to the enclosing repository.
Keep missing-package site and configuration lookups inside the rendered fixture tree.
…gnore A fresh clone of a repo that previously committed great-docs/.gitignore (the tool's own, from an earlier build) failed the pre-build ownership check, since only .gitignore survives a commit while _quarto.yml never does. The check now also accepts that exact, pristine state.
has2k1
force-pushed
the
implement-docs-layout
branch
from
September 21, 2026 15:59
fa4431d to
c3d6177
Compare
This branch has not been deployed
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
1 participant
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 adds a documentation layout that keeps great-docs.yml, documentation sources, and build output together under docs/ (or a custom directory), instead of scattered across the package root. It's the default for new projects; existing root-layout projects keep working unchanged, and a new great-docs migrate-layout command previews and applies the move for projects that want to switch.
Closes #329.