Repository navigation
Add composition pages with discovery-time compose metadata - #345
Merged
Merged
Conversation
Coverage Report for CI Build 41579359755Warning No base build found for commit Coverage: 96.731%Details
Uncovered Changes
Coverage RegressionsRequires a base build to compare against. How to fix this → Coverage Stats
💛 - Coveralls |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The public generated-layout type omits compose, rejecting runtime-supported usage during type checking, and the acceptance-fixture README still documents the obsolete emit API.
2 open issues
What changed in this PR
Adds composition pages to DOMStack’s discovery and build pipelines, allowing source content to remain available for data collection and explicit rendering without publishing standalone page output.
Changes:
- Adds discovery-time
composemetadata, generated-definition support, output suppression, and regression coverage for drafts and watch cleanup. - Converts Cargo / Like’s eight slides to composition pages with homepage-anchor navigation.
- Organizes specialized documentation under Advanced and adds navigation, anchor, and link checks.
| File | Description |
|---|---|
type-tests/index.test.ts |
Checks public composition metadata types. |
test-cases/composition-pages/src/slides/page.vars.js |
Guards against automatic slide output hooks. |
test-cases/composition-pages/src/slides/page.compose.md |
Adds the first composition fixture. |
test-cases/composition-pages/src/slides/chapter.compose.md |
Adds a loose Markdown composition fixture. |
test-cases/composition-pages/src/root.layout.js |
Exercises layout rendering and output suppression. |
test-cases/composition-pages/src/page.js |
Renders collected fragments and explicit previews. |
test-cases/composition-pages/src/global.data.js |
Collects composition metadata and rendered content. |
test-cases/composition-pages/src/explicit.md |
Provides a standalone-output comparison. |
test-cases/composition-pages/src/default.md |
Provides a normal publishing fixture. |
test-cases/composition-pages/README.md |
Describes the acceptance site. |
test-cases/composition-pages/index.test.js |
Checks rendering, suppressed outputs, and ownership. |
site/layouts/docs/advanced-guides.test.js |
Checks Advanced navigation, anchors, and links. |
README.md |
Links to the Advanced manifest guide. |
plans/.keep |
Plans-directory placeholder. |
lib/watch/plan.test.js |
Adds composition metadata to fixtures. |
lib/watch/page-output-ledger.js |
Clarifies empty-output ownership in comments. |
lib/watch/dependency-index.test.js |
Updates page metadata fixtures. |
lib/watch/dependency-analysis.test.js |
Updates page metadata fixtures. |
lib/watch/composition-pages.test.js |
Covers renames, cleanup, data updates, and assets. |
lib/identify-pages.test.js |
Covers composition discovery, precedence, and drafts. |
lib/identify-pages.js |
Derives composition metadata and output names. |
lib/file-conventions.test.js |
Tests composition filename classification. |
lib/file-conventions.js |
Registers supported composition filenames. |
lib/build-pages/worker/protocol.test.js |
Updates worker page metadata fixtures. |
lib/build-pages/source-preparation/markdown-cache.test.js |
Updates Markdown cache fixtures. |
lib/build-pages/page/page-data.test.js |
Updates page-data fixtures. |
lib/build-pages/page/page-data-renderer.test.js |
Updates renderer fixtures. |
lib/build-pages/page/page-data-page-outputs.test.js |
Updates output-hook fixtures. |
lib/build-pages/page/composition-pages.test.js |
Tests suppression, vars independence, and output claims. |
lib/build-pages/page-builders/md/lazy-renderer.test.js |
Updates lazy Markdown fixtures. |
lib/build-pages/page-builders/md/index.test.js |
Updates Markdown builder fixtures. |
lib/build-pages/page-builders/lazy-handlebars.test.js |
Updates Handlebars fixtures. |
lib/build-pages/outputs/page-writer.js |
Skips automatic composition-page output. |
lib/build-pages/outputs/page-outputs.js |
Exposes composition metadata on hook handles. |
lib/build-pages/index.js |
Declares the generated-page composition option. |
lib/build-pages/generated-pages/index.test.js |
Tests composition validation and collision handling. |
lib/build-pages/generated-pages/index.js |
Normalizes composition flags and skips output claims. |
lib/build-pages/build.js |
Excludes generated compositions from output tracking. |
examples/cargo-like/tests/site.browser.mjs |
Tests homepage-only slides and absent standalone routes. |
examples/cargo-like/src/slides/study/page.compose.md |
Converts Study to composition content. |
examples/cargo-like/src/slides/opening/page.compose.md |
Converts Opening to composition content. |
examples/cargo-like/src/slides/motion/page.compose.md |
Converts Motion to composition content. |
examples/cargo-like/src/slides/interval/page.compose.md |
Converts Interval to composition content. |
examples/cargo-like/src/slides/contact/page.compose.md |
Converts Contact to composition content. |
examples/cargo-like/src/slides/composition/page.compose.md |
Converts Composition to embedded content. |
examples/cargo-like/src/slides/colophon/page.compose.md |
Converts Colophon to composition content. |
examples/cargo-like/src/slides/collection/page.compose.md |
Converts Collection to composition content. |
examples/cargo-like/src/page.ts |
Removes the obsolete view selector. |
examples/cargo-like/src/page.css |
Removes standalone-slide styling. |
examples/cargo-like/src/layouts/slide.layout.ts |
Removes the standalone slide layout. |
examples/cargo-like/src/layouts/root.layout.ts |
Uses collected chapter URLs and removes view metadata. |
examples/cargo-like/src/globals/client/navigation.ts |
Simplifies navigation for homepage-only slides. |
examples/cargo-like/src/global.data.ts |
Collects composition slides with homepage-anchor URLs. |
examples/cargo-like/src/components/slide.ts |
Removes standalone rendering behavior. |
examples/cargo-like/README.md |
Documents composition authoring and deployment cleanup. |
examples/cargo-like/package.json |
Cleans local output before building. |
docs/workers/README.md |
Links to the relocated manifest reference. |
docs/typescript/README.md |
Links to advanced type contracts. |
docs/pages/README.md |
Introduces composition pages and links advanced output guidance. |
docs/layouts/README.md |
Retains introductions and links detailed advanced guidance. |
docs/implementation/README.md |
Updates the manifest reference link. |
docs/generation/README.md |
Documents generated compositions and links registry guidance. |
docs/data/README.md |
Documents composition metadata and explicit rendering. |
docs/advanced/README.md |
Adds the Advanced landing page. |
docs/advanced/page-outputs/README.md |
Consolidates output-hook and ownership guidance. |
docs/advanced/output-manifest/README.md |
Relocates manifest configuration and integration guidance. |
docs/advanced/layout-registry/README.md |
Consolidates registry and rendering type contracts. |
docs/advanced/incremental-global-data/README.md |
Relocates saved-state and indexing guidance. |
docs/advanced/composition-pages/README.md |
Documents composition filenames, rendering, and generated definitions. |
Review effort: Balanced
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.
Summary
Add composition pages: ordinary pages that remain available to the pages and data pipelines without automatically publishing standalone output.
.composefilenames across supported page types, includingpage.compose.md,README.compose.md, module/HTML pages, and loose Markdown.pageInfo.compose; composition is not controlled or overridden by page vars..compose.draftsuffix: enabling drafts includes their content without enabling standalone output.workers.json.composeon generated definitions and avoid reserving output paths for composition pages.Advanced documentation
Organize specialized composition, output control, incremental processing, and typing guidance under Advanced, while keeping core authoring references focused.
Keep concise introductions and links in Pages, Data, Workers, Layouts, Generation, and TypeScript, preserving the existing core section anchors and updating cross-references.
Add tests against the checked-in docs for Advanced navigation order, preserved reference anchors, and local links to rendered headings.
Design
Composition status is determined during discovery, so all pipelines use the same authoritative metadata without variable-cascade overrides, replacement
siteDataobjects, or an extra initialization callback.The Cargo / Like example now uses eight composition pages to build its homepage, with chapter navigation through homepage anchors and no standalone slide HTML.
Remove the standalone slide layout and preview-only behavior, clean local output before building, and document removal of previously deployed slide HTML where remote cleanup is disabled.
Validation
node --test— 879 tests passed.npm run build:domstackafter documentation reorganization.npm run test:tsc.npm run test:neostandard.The existing manifest/lockfile mismatch prevented
npm ci; local dependencies were restored without changing dependency files.The changelog is unchanged because it is generated from commits.