influxdata / influxdata/docs-v2

Hugo output is not reproducible: shortcode placeholder counter and taxonomy title casing vary between identical builds

Open
#7,619 0 comments 0 reactions 0 assignees View on GitHub
area:ci
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.