Repository navigation
Add a docs/ layout by default and a migrate-layout command - #354
Merged
Merged
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.
A file merely sharing a name with a packaging manifest, such as a setup.py helper script nested under an _includes folder, doesn't mean real package metadata is mixed into the docs unless it sits at the documentation source's own top level. Stop treating a deeper match as a conflict; a top-level match still blocks as before. A migration can't fix a reference that already pointed nowhere before the move. Report it as a follow-up note to review instead of blocking migration on it, and leave the reference text untouched either way.
…Hub Actions Migration used to only flag automation scripts that still referenced the legacy great-docs/_site output path, leaving the fix to the user. For Makefiles, justfiles, and GitHub Actions workflows, apply the fix directly: substitute the old site path for the new one, the same way other file edits are proposed and applied. Other automation files, and any bare reference to the old build directory without a _site suffix, still only get a note, since the new layout has no single directory that plays the same role.
Preserve the generated-file header when static API-reference analysis rewrites the Quarto configuration. This keeps the rendered build recognisable during migration.
Try docs-website before doc/ so an existing docs/ directory that cannot be migrated remains the preferred destination.
Allow a configured documentation source to remain at its destination without treating it as a new discovery conflict.
Exempt an in-place source only when its configuration field matches the discovery role. This avoids discovering one directory under two roles after migration.
Keep tracked freeze files tracked when moving the cache into an ignored directory. Rebase supported bibliography paths and include their files in preview validation.
Show the migration command after a clean preview. When blockers remain, explain them and provide a complete agent prompt while keeping successful documentation builds available.
Keep root-layout migration guidance visible when inspection fails and preserve YAML frontmatter while rebasing page bibliographies. Update rendered CSS and bibliography fixtures for current layouts, and run the live skill URL check in the integration suite.
This prevents the test from breaking ci
has2k1
force-pushed
the
implement-docs-layout
branch
from
September 28, 2026 13:51
945e9f0 to
d812fd6
Compare
has2k1
changed the title
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
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.