influxdata / influxdata/docs-v2
Hugo output is not reproducible: shortcode placeholder counter and taxonomy title casing vary between identical builds
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Summary
Two Hugo builds of **identical** code produce different HTML on about 26 of
5,959 pages. Verified with a control build: same commit, same config, built
twice to separate destinations.
This is distinct from #7408, which covers duplicate target paths from alias
collisions. These are two different causes, both order-dependent.
## Evidence
### 1. Shortcode placeholder counter leaks into heading IDs
`influxdb/v2/api-guide/api_intro/`:
```
-
+
```
Hugo's internal shortcode placeholder token is reaching the rendered heading ID.
The number depends on build order, so the anchor changes between builds. Any
link to such an anchor is unstable, and the ID is meaningless to readers either
way.
### 2. Taxonomy title casing flips
```
influxdb3/core/tags/influxql 'InfluxQL ...' -> 'Influxql ...'
influxdb3/enterprise/tags/cli 'Cli ...' -> 'CLI ...'
influxdb/cloud/tags/javascript 'Javascript ...' -> 'JavaScript ...'
```
The casing depends on which page Hugo reads the term from first. Note it flips in
**both** directions within a single build, which rules out a one-way
normalization bug.
### 3. Asset fingerprint churn (separate, but it hides the above)
`main..js` and its `integrity=` attribute change between builds and
appear in every page, so a naive `diff -rq` reports ~4,800 changed files and
buries the 26 real ones.
## Impact
- Heading anchors and taxonomy page titles are not stable across deploys.
- **It makes regression testing hard.** Comparing a baseline build to a changed
build requires normalizing fingerprints and then subtracting a control run,
otherwise every diff looks enormous. This cost real time during the InfluxDB v1
shared-content migration.
## Suggested next steps
1. Find why the shortcode placeholder survives into heading IDs -- likely a
heading whose text is produced by a shortcode, rendered before replacement.
2. Give taxonomy terms explicit titles (or a normalization) so casing does not
depend on read order.
3. Consider a CI job that builds twice and diffs, to keep new nondeterminism from
creeping in.
## Reproducing
```sh
npx hugo --destination /tmp/pub-a
npx hugo --destination /tmp/pub-b
# normalize \.[0-9a-f]{64}\.(js|css) and integrity="sha256-..." before comparing
```
Note that `diff -rq --include="*.html"` silently ignores `--include`; filter the
file list yourself.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by running the two `npx hugo` builds from the reproduction section, then normalize asset fingerprints and compare the remaining HTML differences. Trace how shortcode placeholders reach heading IDs and how taxonomy terms acquire title casing; done means repeated identical builds produce stable heading anchors and taxonomy titles, with nondeterministic differences covered by the proposed CI check.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- hugo, javascript
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100