Hugo on TurboVision

Building the Reader Tag Cloud

Thu, 25 Jun 2026 00:00:00 +0000

Weight, grayscale, ordering, and why the cloud is not random by accident

The /tags/ page in the reader theme started as a perfectly ordinary taxonomy page. That was correct in the narrow Hugo sense and wrong in the editorial sense. A plain list tells you that tags exist. It does not tell you which ones dominate the corpus, which ones are one-off curiosities, or which ones form the real conceptual backbone of the site.

The goal of the tag cloud was not to make the page decorative. The goal was to make it legible as a structural overview. A useful cloud must answer three questions quickly:

what topics are central,
what topics are marginal,
how much visual emphasis can be added before the page turns into noise.

That third question matters more than people admit. Tag clouds are easy to make ugly. If you give them color for novelty, weight for count, random order for “organic feel”, and large size swings for drama, they stop being navigation and turn into a poster. This theme wanted the opposite: quiet, readable, monochrome, but still meaningfully weighted.

So the implementation followed a few deliberate rules.

Start from count, but do not trust count alone

The source set is Hugo’s normal tag taxonomy ordered by count. That part is conventional and direct:

`1`	`{{- $allTagsRaw := .Site.Taxonomies.tags.ByCount -}}`

This gives a stable descending list of tags by article count. But using that count directly as a visual signal has a problem: a large corpus almost always has a long tail. A few tags are very common, many tags appear only once or twice, and a linear scale tends to flatten the middle or overinflate the top.

That is why the cloud does not use a linear count weight anymore. It uses a logarithmic normalization. The implementation computes the natural logarithm of the minimum count, the maximum count, and each tag’s own count, then normalizes the result into a 0..1 weight interval:

{{- $logMin := math.Log (float $minCount) -}}
{{- $logMax := math.Log (float $maxCount) -}}
{{- $logRange := sub $logMax $logMin -}}
{{- $logCount := math.Log (float $t.Count) -}}
{{- $weight := div (sub $logCount $logMin) $logRange -}}

The effect on the page is practical rather than theoretical. Heavy tags still read as heavy, but medium-frequency tags do not collapse into one indistinguishable visual band. They keep enough separation to matter.

Size and weight are separate, but derived from the same signal

Once the normalized weight exists, the cloud uses it twice:

to interpolate font size,
and to interpolate font weight.

Both sets of bounds are configurable in hugo-reader.toml:

[params.tagcloud]
  minFontSize = 0.6
  maxFontSize = 3.5
  minFontWeight = 350
  maxFontWeight = 1000

The template then interpolates between those bounds:

1
2

{{- $fontSize := add $minSize (mul $weight (sub $maxSize $minSize)) -}}
{{- $fontWeight := int (add (float $minWeight) (mul $weight (sub (float $maxWeight) (float $minWeight)))) -}}

That may sound obvious, but it matters that both are configurable. The cloud is not locked to one aesthetic. If the page starts feeling too shouty, the upper size bound can come down. If the differences feel too timid, the weight range can widen. The implementation keeps the knobs where they belong: in configuration, not in the template body.

Color is monochrome on purpose

The color model is intentionally narrow. Instead of assigning hues, the cloud hashes the tag name into a grayscale value. The target range is also configurable:

1
2
3

[params.tagcloud]
  minGrey = 0
  maxGrey = 160

The code hashes the tag name deterministically and then remaps the internal 0..192 scale into the configured grey bounds:

{{- $hash := 0 -}}
{{- range (split $t.Page.Title "") -}}
  {{- $hash = mod (add (mul $hash 31) (len .)) 193 -}}
{{- end -}}
{{- $greyRange := sub $maxGrey $minGrey -}}
{{- $grey := int (add (float $minGrey) (mul (div (float $hash) 192.0) (float $greyRange))) -}}

This gives variation without turning the page into a rainbow. Tags do not compete through hue. They differ through density, scale, and value. That is much more compatible with the rest of the reader theme, where structure is supposed to emerge from calm contrast rather than accent color.

Placement is not random, and that is a feature

A true random shuffle would make the page feel unstable between rebuilds unless a seed were fixed, and Hugo templates are not a great place for high-quality randomness anyway. The implementation therefore uses a two-step placement model:

alternate front/back insertion so heavy tags tend toward the center,
apply a deterministic pseudo-shuffle to avoid overly rigid symmetry.

The first part is simple and intentional. Each count-sorted tag is alternately pushed into a front or back list. Reversing the front list and then appending the back list yields a sequence where the heaviest cluster around the middle of the final run.

That alone was too orderly. So the second step performs bounded displacement rounds. Those rounds are also configurable:

1
2
3

[params.tagcloud]
  shuffleRounds = 45
  shuffleWindow = 35

The important distinction is this:

shuffleRounds means how many displacement operations happen,
shuffleWindow means how far one selected tag may move left or right in a single operation.

The code does not just swap neighbors repeatedly. It picks a source index deterministically from the round number, computes a displacement from the tag-name hash plus round number, clamps the destination into the list bounds, removes the tag, and reinserts it at the new index.

That means the “window” is a real movement window, not just a disguised repeat count. The cloud still stays deterministic from build to build, but it stops looking mechanically mirrored.

Singleton tags should not waste a click

One subtle usability improvement is that tags with exactly one article do not link to a one-entry tag archive. They link directly to the article itself.

That decision looks small, but it respects user intent. If a tag can only take you to one place, the intermediate overview is ceremony. The cloud now checks count and changes the target URL accordingly:

{{- $targetUrl := $t.Page.RelPermalink -}}
{{- if eq $t.Count 1 -}}
  {{- $singlePage := index $t.Pages 0 -}}
  {{- $targetUrl = $singlePage.RelPermalink -}}
{{- end -}}

The result is that dense tags behave like topic indexes, and singleton tags behave like direct shortcuts.

Why the cloud feels calmer than most clouds

The visual result comes from constraint:

no hue circus,
no explosive size jumps,
deterministic placement,
bounded pseudo-shuffle,
centered flowing layout,
white-space: nowrap on each tag so the unit stays intact.

The CSS is correspondingly spare:

.tag-cloud {
  text-align: center;
  line-height: 0.8;
  word-spacing: -1em;
  animation: tag-cloud-settle 5s cubic-bezier(0.18, 0.92, 0.25, 1) 1 both;
}

.tag-cloud-item {
  display: inline;
  white-space: nowrap;
  text-decoration: none;
  padding: 0 0.2em;
  text-shadow: 0px 0px 2px rgba(0, 0, 0, 0.25);
  transition:
    text-shadow 3.5s ease,
    color 3.5s ease,
    opacity 3.5s ease;
}

.tag-cloud-item:hover {
  text-shadow: 0px 0px 8px rgba(0, 0, 0, 1);
  color: #fff !important;
  opacity: 0.6;
  transition:
    text-shadow 0.2s ease,
    color 0.2s ease,
    opacity 0.2s ease;
}

@keyframes tag-cloud-settle {
  from {
    opacity: 0;
    line-height: 3.4;
    word-spacing: 2.6em;
  }
  to {
    opacity: 1;
    line-height: 0.8;
    word-spacing: -1em;
  }
}

This is not an attempt to look algorithmic. It is an attempt to let the algorithm do just enough work that the page feels informative before it feels designed.

There are two motion cues in that CSS that matter:

on page load, the cloud starts with exaggerated spacing and then settles into its dense final form,
on hover, a tag brightens and gains a stronger shadow quickly, then relaxes back slowly.

Those are tiny effects, but they keep the page from feeling dead-static. The cloud does not need to pulse or wiggle. It only needs just enough motion to suggest that taxonomy here is active structure, not a frozen appendix.

Effect on the reader

The practical effect is that the page becomes scannable at two speeds.

At a glance:

the large center cluster shows the dominant themes,
the sparse outskirts show one-off or niche topics,
the grayscale variation prevents the cloud from feeling dead-flat.

At a deliberate reading pace:

the left pane lets you find exact tags alphabetically,
singleton tags get you straight to content,
heavier tags invite exploration because they look consequential without shouting.

Why the implementation is deterministic

The cloud is meant to feel lively, but not unstable. That is why all the placement and shuffle logic is deterministic. Rebuilds should not cause the same tag cloud to jump around randomly when nothing in the corpus changed.

So the page gets variation without losing trust:

count drives prominence,
name hash drives grayscale,
deterministic placement drives center-of-mass,
deterministic displacement rounds soften the symmetry.

That is the whole design philosophy in one sentence: variation without drift.

That balance was the real goal. Not “build a tag cloud.” Build a page where taxonomy behaves like editorial structure instead of storage metadata.

Hugo dev server CSS changes not updating in browser

Tue, 23 Jun 2026 00:00:00 +0000

Hugo dev server CSS changes not updating in browser

Problem

When running hugo server in development mode, edits to a theme CSS file are detected by the dev server, but the browser continues to show the old CSS. Normal reload and hard reload do not apply the change. Restarting the Hugo dev server and then reloading the page makes the CSS change visible.

Observed log example:

Change detected, rebuilding site (#1).
2026-06-23 13:23:58.624 +0000
Asset changed /css/theme.css
Web Server is available at http://localhost:1314/ (bind address 0.0.0.0)
Total in 26 ms

This shows that Hugo detects the asset change and rebuilds, but the served/client-visible stylesheet does not update.

Relevant template code

{{- $css := resources.FromString "css/theme.css" (readFile "themes/reader/assets/css/theme.css") -}}
{{- if hugo.IsProduction -}}
  {{- $css = $css | resources.Minify | resources.Fingerprint -}}
{{- end -}}
<link rel="stylesheet" href="{{ $css.RelPermalink }}"{{ if hugo.IsProduction }} integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous"{{ end }}>

Diagnosis

The likely cause is the use of:

`1`	`resources.FromString "css/theme.css" (readFile "themes/reader/assets/css/theme.css")`

This creates a synthetic Hugo resource from a string. It bypasses the normal Hugo Pipes resource graph for files in assets/. As a result, Hugo may detect that the source CSS file changed, but the resource cache/live-reload chain may not invalidate the synthetic stylesheet correctly.

This explains why:

the dev server logs the CSS change;
build.cachebusters does not fix the issue;
browser reloads still show the old stylesheet;
restarting the dev server clears the stale state and makes the new CSS visible.

resources.FromString is intended for resources created from generated string content. For an actual file under assets/, use resources.Get instead.

Corrected template code

Replace the current resources.FromString + readFile pattern with a normal asset lookup:

{{- with resources.Get "css/theme.css" -}}
  {{- $css := . -}}
  {{- if hugo.IsProduction -}}
    {{- $css = $css | resources.Minify | resources.Fingerprint -}}
  {{- end -}}
  <link rel="stylesheet" href="{{ $css.RelPermalink }}"{{ if hugo.IsProduction }} integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous"{{ end }}>
{{- end -}}

Do not include the theme directory prefix in resources.Get.

This file:

`1`	`themes/reader/assets/css/theme.css`

should be referenced as:

`1`	`resources.Get "css/theme.css"`

Theme assets are part of Hugo’s global asset lookup path.

Recommended dev-server command

Use this while testing the fix:

`1`	`hugo server --disableFastRender --noHTTPCache --ignoreCache`

Purpose:

--disableFastRender: avoids partial rebuild behavior masking template/resource changes;
--noHTTPCache: disables Hugo’s HTTP cache headers;
--ignoreCache: avoids using configured caches during the build.

These flags are useful for diagnosis, but the primary fix is replacing resources.FromString with resources.Get.

Cachebusters

The cachebuster configuration is not expected to fix the current template because the pipeline input is not a normal asset resource. It is a string generated by readFile and wrapped with resources.FromString.

A normal cachebuster rule for theme assets should match paths relative to assets/, not paths starting with themes/<theme>/assets/.

Example:

[build]
  useResourceCacheWhen = 'never'

  [[build.cachebusters]]
    source = 'assets/.*\.(scss|sass|css)$'
    target = '(css|scss|sass)'

But after switching to resources.Get, cachebusters may be unnecessary for plain CSS.

Verification

After changing the template, edit themes/reader/assets/css/theme.css, then check the served CSS directly:

`1`	`curl -s http://localhost:1314/css/theme.css \| grep 'some-new-css-token'`

Interpretation:

If curl shows the new CSS but the browser does not, the problem is browser-side caching, live-reload CSS injection, or a service worker.
If curl still shows the old CSS, the problem remains in Hugo’s resource/cache pipeline.

Additional check

If the CSS include is inside a cached partial, avoid this in development:

`1`	`{{ partialCached "..." . }}`

Use this instead:

`1`	`{{ partial "..." . }}`

A cached partial can keep emitting an old resource URL or stale generated markup.

Bottom line

This is a known class of Hugo dev-server/resource-cache behavior. In this specific case, the actionable fix is to stop using resources.FromString with readFile for a real theme asset and use resources.Get "css/theme.css" instead.

Relevant references:

Hugo resources.FromString: https://gohugo.io/hugo-pipes/resource-from-string/
Hugo resources.Get: https://gohugo.io/functions/resources/get/
Hugo build cachebusters: https://gohugo.io/configuration/build/
Related Hugo forum report: https://discourse.gohugo.io/t/resources-fromstring-breaks-resource-caching-reloading/52758
Related Hugo issue for theme Sass/CSS refresh behavior: https://github.com/gohugoio/hugo/issues/12395