influxdata / influxdata/docs-v2
Replace request-information.md alias stopgap with real pages + a CI guardrail
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Background
`content/influxdb3/cloud/request-information.md` is a stopgap introduced in #7338.
It absorbs links from shared content that point to Cloud pages that don't exist
yet. It does this two ways:
- ~49 `aliases` that redirect not-yet-published Cloud paths to the page.
- ~58 hidden anchor ``s so the link checker can resolve `#fragment` deep
links against the redirect target.
This unblocked the CI link-check without inventing pages we don't have. It's a
reasonable bridge, but it's a maintenance footgun.
## The problem
The two lists must be hand-synced with shared content, and there's no loud
signal when they go stale:
- When a real Cloud page is later published at an aliased path, Hugo doesn't
fail — an alias colliding with a real page emits only a build *warning*, and
the real page wins. The alias silently goes dead and its hidden anchors
orphan.
- A catch-all anchor list can mask a genuinely broken `#fragment` for any path
still redirecting here.
So "remove the alias and anchors when the page ships" is an obligation nobody is
prompted to fulfill.
## Proposed work
1. **Add a CI guardrail.** A test in the link-check/test pipeline that reads the
`aliases` from `request-information.md` and asserts none of them resolve to a
real built page in `public/` (only the alias redirect should exist at that
path). The day a real page lands at an aliased path, the test fails and
points at the line to delete.
2. **Port truly-shared content** so Cloud has real pages for the reference/guide
paths that are genuinely shared (SQL/InfluxQL reference, line protocol,
glossary, naming restrictions, etc.), shrinking the alias list to only the
paths that are still legitimately absent (for example, separately generated
API reference). Separate PR.
3. **Drain the stopgap.** As pages ship, remove the corresponding aliases and
anchors. The guardrail in (1) enforces this.
## Larger plan
This stopgap is a symptom of reference content living inside product-specific
sections. The larger plan is to lift most reference content (SQL, InfluxQL,
line protocol, glossary, internals, etc.) up out of per-product trees so
products reference shared canonical pages instead of each maintaining (or
stubbing) their own. Doing that removes the need for per-product alias dumps
like this one. Tracked here as the destination this cleanup should converge on;
the relocation itself warrants its own planning/PRs.
## Cleanup trigger (for now)
When a Cloud page is published at one of the aliased paths in
`request-information.md`, remove that alias and any hidden anchors that belonged
to it.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with content/influxdb3/cloud/request-information.md and inspect the aliases and hidden anchors against the built public/ tree. Then trace the existing link-check/test pipeline to identify where the guardrail belongs. Done means the check flags aliases that resolve to real built pages and identifies the alias lines to remove; content porting and broader relocation are separate work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- hugo
- Domain
- ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100