influxdata / influxdata/docs-v2

Phase 2 AI visibility: inverted-transclusion mechanism spike (IA content sharing)

Open
#7,297 0 comments 0 reactions 0 assignees View on GitHub
enhancement InfluxDB v3 platform
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.