Goal
Decide the sharing mechanism for the job-led IA before committing engineering effort. The IA's "engine docs live once with thin overlays" model needs some way to share content across Core / Enterprise and deployment variants — but the two candidate approaches (transclusion-default vs. conventional split) have different cost/benefit profiles and the original plan's LLM-benefit claims need empirical grounding.
This issue is a design decision, not implementation. Implementation issues follow once the decision lands.
Parent: #7230
Background
Two routes deliver the same IA outcome:
Route 1 — Transclusion default. Engine docs live at /enterprise/... (canonical). Core's engine pages use a ref-include shortcode to pull engine content inline. Pages render as if the content were local.
Route 2 — Conventional split. Engine docs live at /enterprise/... (canonical). Core's engine pages are short stubs with canonical_url: /enterprise/... and link to the Enterprise page for the bulk of the content. Deployment pages cover only what genuinely differs.
Decision inputs
| Factor |
Route 1 (transclusion) |
Route 2 (split) |
| LLM retrieval |
Duplicate embeddings at multiple URLs (canonical isn't honored by most retrievers) |
One embedding per concept |
| Reader UX |
Everything inline, no navigation |
Some reader hops between products |
| Engineering cost |
New shortcode + fragment library + reverse-index tooling + CI lint |
Uses existing source: and canonical_url: frontmatter |
| Failure mode |
Fragment sprawl, drift across consumers |
Core feels like a stub product |
| Existing pattern |
Parallel to current content/shared/ mechanism |
Builds on current pattern |
A hybrid is also viable: Route 2 by default, Route 1 reserved for small frequently-reused snippets (e.g., a 60-word "how to pass a token in the Authorization header" fragment).
Tasks
Out of scope
- Migration guides per competitor (separate content workstream)
- Phase 1 IA skeleton (predecessor)
- Phase 3 editorial discipline (successor)
Goal
Decide the sharing mechanism for the job-led IA before committing engineering effort. The IA's "engine docs live once with thin overlays" model needs some way to share content across Core / Enterprise and deployment variants — but the two candidate approaches (transclusion-default vs. conventional split) have different cost/benefit profiles and the original plan's LLM-benefit claims need empirical grounding.
This issue is a design decision, not implementation. Implementation issues follow once the decision lands.
Parent: #7230
Background
Two routes deliver the same IA outcome:
Route 1 — Transclusion default. Engine docs live at
/enterprise/...(canonical). Core's engine pages use aref-includeshortcode to pull engine content inline. Pages render as if the content were local.Route 2 — Conventional split. Engine docs live at
/enterprise/...(canonical). Core's engine pages are short stubs withcanonical_url: /enterprise/...and link to the Enterprise page for the bulk of the content. Deployment pages cover only what genuinely differs.Decision inputs
source:andcanonical_url:frontmattercontent/shared/mechanismA hybrid is also viable: Route 2 by default, Route 1 reserved for small frequently-reused snippets (e.g., a 60-word "how to pass a token in the
Authorizationheader" fragment).Tasks
ref-includeshortcode, fragment design discipline, reverse-index toolingshow-in/hide-inpages using the chosen route. Identify candidates withgrep -rE '\{\{<\s*(show-in|hide-in)' content/ranked by occurrenceOut of scope