Inconsistent range execution

I am trying to render out a generated table of contents for this specific page using a partial. I feed it a dictionary of shape map[string]interface{} and tell it to execute based on that. For some reason, though, it renders very inconsistently; when I do a fresh hugo serve it does not render the range loop of the map, despite getting the proper data (verified using debug.Dump), but when saving the partial’s file page, it renders correctly.. On our CI deployment, it does not render at all.

The code is simply:

<ul class="list-style-type-none">
          {{ range $k, $v := . }}
            {{ template "toc-subheading" (dict "info" $v "level" 0 "title" $k) }}
          {{ end }}
        </ul>

View code in context [here](RecoilEngine/doc/site/layouts/partials/generated_toc.html at ae43a1252318cb11dac66342503977042122cc02 · SlashScreen/RecoilEngine · GitHub)

This template is invoked [here](RecoilEngine/doc/site/layouts/docs/lua_api.html at ae43a1252318cb11dac66342503977042122cc02 · SlashScreen/RecoilEngine · GitHub)

If you have any insight, I would appreciate it!

typical problems with inconsistent builds are (list maybe incomplete)

between ci and local are:

  • different hugo versions
  • different sources
    • hugo modules fetched
    • git submodules
  • committed public folder

between local runs of hugo/hugo server

  • incompatibilities between sources and hugo version
  • old content in public
  • context problems ., $
  • wrong use of
    • global page function
    • page Store
    • partialCached
  • side effects with import orders?
your repo
  • looks like your ci does not load submodules (if they are needed)
  • go.sum, mod list many modules that seem to be unused
    a toc.html is present in 7 modules :wink:
  • seems to miss some parts ???
  • I cloned master incl submodules
  • I vendored the modules (>1GB)
  • I cannot find the mentioned partials anywhere

I would recommend to clean that up a bit :wink: (currently around 2GB)

We would need a reproducible repo to get that up and running. If there’s something special, please provide instructions.

and an example page listed would be nice and a statement what is missing there.

View Lua API Reference – Recoil Engine to see my work in progress branch. On the right is a table of contents that currently has dumped data passed to it. It is supposed to render the items in a list above the dumped docs.

As for why you can’t see anything and why the site is weird for you, it’s because you are surely cloning the master branch. I am working on site_formatting_template as I linked, although I understand missing that detail, and I should have mentioned that in the original post. My bad.

I updated the Hugo version both on my computer and in CI to be the latest released as of writing (I think). Note that this repository is a game engine, and that the item of interest is the doc folder. Again, I did not indicate that. None of the submodules are necessary to build the site. The theme is expected to be vendored, though.

One thing I will also mention is that there is a readme for building the website with all of the data automatically populated. I will not force you to do that. Here is a heavily truncated version of the API docs it needs, since the page in question is the docs page. Place this json file as doc.json in the data folder. doc.json - Pastebin.com

I apologize for missing information in my earlier post. I posted it late at night in exasperation, and didn’t think it through.

just some findings - no real idea yet.

  • you use recursive inline templates in baseof and others… I’m unsure if that - especially for baseof - is allowed
  • if I remember right, no code is allowed before the first block definition…somewhere in the docs
  • it seems like the definition of the these defined templates comes later after the page is rendered and then on update it finds it …
  • maybe a lookup thing v145->v152.1
  • maybe convert these defined templates to partials

some housekeeping :

with that in hugo.toml

[module]
	[[module.imports]]
	path = "github.com/imfing/hextra"

this go mod looks strange

module recoil.com

go 1.22.0

require (
	github.com/McShelby/hugo-theme-relearn v0.0.0-20250501121145-0b83617ee9da // indirect
	github.com/SlashScreen/hugo-book v0.0.0-20250508083807-6df4e9da73c9 // indirect
	github.com/alex-shpak/hugo-book v0.0.0-20250428224046-9405c4c3d7c7 // indirect
	github.com/chipzoller/hugo-clarity v0.0.0-20250411201404-a8ce0375e8cb // indirect
	github.com/colinwilson/lotusdocs v0.2.0 // indirect
	github.com/gohugoio/hugo-mod-bootstrap-scss/v5 v5.20300.20400 // indirect
	github.com/google/docsy v0.11.0 // indirect
	github.com/imfing/hextra v0.9.7 // indirect
	github.com/onweru/compose v0.0.0-20250123191918-095317e5c72c // indirect
	github.com/thingsym/hugo-theme-techdoc v1.0.2 // indirect
)

it takes a log of time for hugo to initialize and I don’t know if something there may break others.

If you don’t need the others → go mod tidy and maybe clean up some caches…

I cleaned out the go mod in the most recent commit to the branch I am working on (site_formatting_template).

if I remember right, no code is allowed before the first block definition

You mean template definition?

that one Base, but it does not apply to yours (as far as I researched)

regarding go-mod update:

old hextra was 0.9.7 with old layout structure of 0.145
new would be 11+ with new layout structure and some other changes and it won’t build

you have a lot of stuff in your cache that’s magically taken over, so it’s a good idea to clean that up and do fresh clones maybe add cacheDir to localize …

reverted to hextra 0.9.7:

toc-subheading definition.

you define a template in a partial but not as inline => this results in your defined one is not found at the first build.

These lines print only BEFORE

          {{ range $k, $v := . }}
            {{ warnf "BEFORE toc_subheading %4d %-30s : %s" math.Counter templates.Current.Name page.Page }}
            {{/* partial "inline/toc-subheading" (dict "info" $v "level" 0 "title" $k) */}}
            {{ template "toc-subheading" (dict "info" $v "level" 0 "title" $k) }}
          {{ end }}
...
{{- /* define "partials/inline/toc-subheading" */ -}}
{{- define "toc-subheading" -}}
  {{ warnf "IN TOC SUBHEADING  %4d %-30s : %s" math.Counter templates.Current.Name page.Page }}

if you change the commented call and definition to inline , “IN TOC” is also printed but fails due to the content of the variables. → guess you will have to fix up some code here

if you change the loop inside toc-subheading to that one you will get some output to the sidebar

 		{{ range . }}
        		<li><a class="margin-left-1rem" href="#oops"> {{ . }}</a></li>
	     	{{ end }}

Wait, hang on, so I don’t 100% understand what’s going on here. It’s still in the same file, but defined under a path as a partial, and somehow that works? Is the inline path special?

there are some places in the docs.

fe Menu templates

keep in mind that you use the old layout folder structure and thats good cause hextra 9.7 does. and the new one would need adjustments.

I’m the wrong to state on differences and relations using block, template, partial…

i just havent yet seen

  • a layout or baseof defining templates. all use blocks only
  • a partial defining a template without inline