influxdata / influxdata/docs-v2
Fix nondeterministic duplicate target paths in Hugo build
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Summary
`hugo --printPathWarnings` reports 41 content pages whose output path comes from
more than one source: a page that collides with another page's `aliases:`, or
two pages that target the same URL. When multiple sources write one path, Hugo
picks the winner by build order, so the output changes between builds.
Two instances (`influxdb3/cloud-dedicated/reference/cli/` and the v1
`authentication_and_authorization-api/` alias) are fixed separately. This issue
tracks the remaining backlog and a guardrail to prevent new ones.
## Impact
- Hugo can replace a real page with an alias redirect stub, so the URL serves a
meta-refresh instead of content.
- `` and redirect targets change between builds, which
hurts SEO and is hard to debug because it doesn't reproduce reliably.
## Evidence
To reproduce, run `npx hugo --environment production --printPathWarnings`. The
count in parentheses is the number of sources that write each path.
### Content collisions
```
enterprise_influxdb/v1/guides/rebalance/index.html (2)
flux/latest/index.html (2)
flux/latest/introduction/index.html (2)
influxdb/cloud/collect-data/advanced-telegraf/index.html (2)
influxdb/cloud/collect-data/use-telegraf/index.html (2)
influxdb/cloud/reference/flux/stdlib/index.html (2)
influxdb/cloud/tools/client-libraries/js/index.html (2)
influxdb/v1/clients/index.html (2)
influxdb/v2/account-management/offboarding/index.html (2)
influxdb/v2/cloud/account-management/offboarding/index.html (2)
influxdb/v2/cloud/pricing-plans/index.html (2)
influxdb/v2/cloud/rate-limits/index.html (2)
influxdb/v2/collect-data/advanced-telegraf/index.html (2)
influxdb/v2/collect-data/use-telegraf/index.html (2)
influxdb/v2/pricing-plans/index.html (2)
influxdb/v2/query_language/spec/index.html (2)
influxdb/v2/reference/flux/functions/index.html (2)
influxdb/v2/reference/flux/index.html (2)
influxdb/v2/reference/flux/stdlib/index.html (2)
influxdb3/cloud-dedicated/query-data/execute-queries/troubleshoot/index.html (2)
influxdb3/cloud-dedicated/reference/api/client-libraries/go/index.html (2)
influxdb3/cloud-dedicated/reference/client-libraries/flight-sql/go-flightsql/index.html (2)
influxdb3/cloud-dedicated/reference/client-libraries/flight-sql/python-flightsql/index.html (2)
influxdb3/cloud-dedicated/tools/client-libraries/go/index.html (2)
influxdb3/cloud-serverless/query-data/execute-queries/troubleshoot/index.html (2)
influxdb3/cloud-serverless/reference/api/client-libraries/go/index.html (2)
influxdb3/cloud-serverless/reference/client-libraries/flight-sql/go-flightsql/index.html (2)
influxdb3/cloud-serverless/tools/client-libraries/go/index.html (2)
influxdb3/clustered/query-data/execute-queries/troubleshoot/index.html (2)
influxdb3/clustered/reference/api/client-libraries/go/index.html (2)
influxdb3/clustered/reference/client-libraries/flight-sql/go-flightsql/index.html (2)
influxdb3/clustered/tools/client-libraries/go/index.html (2)
influxdb3/core/reference/api/client-libraries/go/index.html (2)
influxdb3/core/reference/client-libraries/flight-sql/go-flightsql/index.html (2)
influxdb3/core/reference/client-libraries/flight-sql/python-flightsql/index.html (2)
influxdb3/core/tools/client-libraries/go/index.html (2)
influxdb3/enterprise/reference/api/client-libraries/go/index.html (2)
influxdb3/enterprise/reference/client-libraries/flight-sql/go-flightsql/index.html (2)
influxdb3/enterprise/reference/client-libraries/flight-sql/python-flightsql/index.html (2)
influxdb3/enterprise/tools/client-libraries/go/index.html (2)
telegraf/v1/administration/troubleshooting/index.html (2)
```
### Shared assets
Confirm these are benign and exclude them from any gate. `/js/main..js` is
the content-hashed bundle that Hugo emits once per product context, and the
`.css.map` entries are theme source maps.
```
/dark-theme.css.map (2)
/js/main.5adb12887b64d1956920da8981f6467b64bfe4dfdaa9de558596ca198f1bee5c.js (39)
/light-theme.css.map (2)
```
## Proposed approach
1. Triage each content collision to identify its two sources.
2. Remove or relocate the offending alias or page. Both instances found so far
were a stale alias that points at a URL a real page already owns.
3. Add a guard to `.github/workflows/pr-render-check.yml`. Start with a
non-blocking `::warning::` annotation to avoid failing on the current
backlog, then make it blocking after the content list reaches zero.
4. Evaluate a complementary static check. `--printPathWarnings` misses some
alias-versus-page collisions—for example, a section `_index.md` that collides
with a child page's alias went undetected in testing. Scanning every
`aliases:` entry and page permalink for duplicates closes that gap.
## Acceptance criteria
- [ ] Content duplicate-target-path warnings reach zero.
- [ ] CI surfaces new duplicate target paths on pull requests, first
non-blocking, then blocking.
- [ ] The team decides whether to add a supplementary alias-dedup check.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Run `npx hugo --environment production --printPathWarnings` and review the listed content paths, excluding the documented shared assets. Triage each collision to its two sources, then update the affected content or aliases. Add a non-blocking duplicate-path warning to `.github/workflows/pr-render-check.yml`; done means content warnings reach zero and CI surfaces new ones.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- build-system, ci-cd, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100