influxdata / influxdata/docs-v2
Phase 2 AI visibility: inverted-transclusion mechanism spike (IA content sharing)
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Why this matters (IA context)
This supports the broader **job-led information architecture (IA)** improvement
tracked in #7230 and kicked off in #7232: six task-oriented sections under
`/influxdb3/enterprise/`, engine documentation that lives once, and deployment
pages that stay thin. That IA only works if there is a clean, low-cost way to
**share content across Core / Enterprise and deployment variants**. This issue
defines that sharing mechanism so the IA migration can proceed without
duplicating prose or scattering content into catch-all sections.
## Goal
Scope the **inverted-transclusion** sharing mechanism in Hugo: make a real,
published, canonical page the authoritative source for shared engine content —
instead of a hidden `content/shared/*.md` stub laced with `show-in`/`hide-in`
conditionals — and define how other products reference or include from it.
This is the implementation half of the Phase 2 mechanism decision. **Blocked on
the #7233 route decision** — if the decision favors a pure conventional split
(stub + `canonical:`), the include tooling here may not be needed.
Parent: #7230 · IA migration: #7232 · Decision: #7233 · Design: `docs/exec-plans/active/2026-06-03-ia-sharing-canonical-validation-design.md`
## Background
Today's pattern is `N thin stubs → 1 hidden /shared/ source`. The authoritative
body lives at a non-published path, every consumer parses conditionals, and no
single real page is the authority. Inverted transclusion flips this to
`1 canonical real page ← N consumers`: the full content lives at one published
URL as clean prose, and consumers reference or include from it. This keeps a
single readable, citable copy per concept — the property the IA needs for both
human readers and LLM retrievers.
The repo already has whole-page transclusion (`source:` + `content/shared/`) and
canonical frontmatter. The genuinely new capability is **sub-page fragment
includes** — reusing a small snippet inline — which `source:` does not support.
## Tasks
- [ ] Decide the authoritative-page model: can a real published page act as the
shared source, or do we keep a `/shared/` source but render it
conditional-free and point `canonical:` at one real consumer?
- [ ] Evaluate whether sub-page fragment includes are actually needed, or whether
whole-page `source:` + `canonical:` covers the IA's sharing needs
- [ ] If fragments are needed: scope a `ref-include` shortcode, the fragment
design discipline, and reverse-index/CI-lint tooling to catch drift
- [ ] Define the `show-in`/`hide-in` exit path: what replaces conditionals in the
authoritative copy
- [ ] Confirm the approach keeps a single clean readable copy per concept for
retrievers/agents
## Out of scope
- The route decision (#7233)
- Bulk content migration (#7232, and the pilot follow-up)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/exec-plans/active/2026-06-03-ia-sharing-canonical-validation-design.md, then inspect the existing whole-page source: transclusion, content/shared/, canonical frontmatter, and show-in/hide-in usage. Resolve the dependency on #7233, evaluate whether source plus canonical is sufficient or whether fragment includes are needed, and document the chosen model, exit path, and validation approach as done.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- hugo
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100