Hugo/Docsy: Custom layout specified in front matter is ignored

[Steph-001]

Hi everyone,
I'm trying to add a per-unit lexicon feature to my Hugo site, which uses the Docsy theme as a Hugo Module.

Goal:
For each unit (e.g., content/units/widgets/_index.md), I want a separate lexicon page (e.g., /units/widgets/lexicon/) that displays vocabulary terms defined in the unit page's front matter.

My Setup:
1. Unit Page: content/units/widgets/_index.md contains the main content and a lexicon: parameter in its front matter holding the vocabulary (list of maps with term and definition).
2. Lexicon Marker Page: I created content/units/widgets/lexicon/_index.md to represent the lexicon page.
3. Lexicon Front Matter: The front matter of content/units/widgets/lexicon/_index.md contains layout: lexicon to explicitly tell Hugo to use a custom layout.

---
title: "Lexicon"
layout: lexicon
# Also tried adding type: units here
---

4. Custom Layout File: I created a layout file initially at layouts/_default/lexicon.html, and later moved it to layouts/units/lexicon.html (since the content is under content/units/, the inferred type should be units). This file is supposed to fetch data from the parent (../_index.md) and display it.
5. Linking: I modified Docsy's layouts/docs/single.html (copied to my project) to successfully add a link from the unit page to the lexicon page (/units/widgets/lexicon/).

The Problem:
While the site builds, the link works, and I navigate to the correct URL (/units/widgets/lexicon/), Hugo seems to be completely ignoring the layout: lexicon directive in the marker file's front matter.

• The rendered lexicon page does not display the vocabulary.
• Crucially, the page is not rendered using my layouts/units/lexicon.html file. I verified this by replacing the layout file's entire content with simple test HTML <h1>TEST LAYOUT</h1> and adding extensive debugging blocks – none of this ever appears on the rendered page. It seems to be falling back to a default Docsy layout.

Troubleshooting Steps Taken (None Worked):

• Placed the layout file in layouts/_default/lexicon.html.
• Placed the layout file in layouts/units/lexicon.html (matching inferred content type).
• Explicitly added type: units to the front matter of content/units/widgets/lexicon/_index.md.
• Renamed the layout file (e.g., vocabdisplay.html) and updated the layout: directive accordingly to rule out naming conflicts.
• Copied Docsy's _default/baseof.html to layouts/units/baseof.html in case a type-specific base layout was required.
• Consistently used hugo server --ignoreCache --disableFastRender to avoid caching issues.

Question:
Why would Hugo ignore the explicit layout: directive in the front matter for this specific page structure (/units/widgets/lexicon/_index.md)? Is there a known interaction with Docsy's module structure, layout lookup order, or _index.md files acting as section heads that I'm missing? How can I force Hugo to use my specified layout file?

Thanks for any insights!

hugo version
hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended linux/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=gohugoio