influxdata / influxdata/docs-v2

Fix nondeterministic duplicate target paths in Hugo build

Open
#7,408 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:ci kind/chore
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.