What happens
With custom menu templates (_menu_template.html and _menu-item_template.html in the input folder), editing one of them while fsdocs watch is running updates the documentation sections of the menu but not the API Reference section. That section keeps rendering with the template as it was when the watch started, until an assembly changes or the watch is restarted.
Reproduction
- Run
fsdocs watch on a site that has both menu templates and API docs (Fantomas is one: https://github.com/fsprojects/fantomas/tree/main/docs).
- Edit
_menu_template.html, for example change the size of the chevron icon in the header.
- Reload a page. The
End-users and Contributors headers show the new markup, the API Reference header still shows the old one.
Observed with 23.0.0-alpha.3. fsdocs build renders both alike, so this is watch only.
Cause
src/fsdocs-tool/DevServer.fs:
menuStamps tracks the menu templates and feeds navInputs, so the documentation navigation is recomputed on an edit. That is why the docs sections do update.apiState is AVal.map2 over the assembly stamps and the crack result only. A menu template edit does not invalidate it, so fsdocs-list-of-namespaces is served from the state built at startup.- Inside
buildApi, GlobalsFor memoises the navigation HTML per page root in a ConcurrentDictionary, so even a fresh call into the same state returns the text rendered from the old template.
The API reference pages themselves carry the same menu and have the same problem.
Suggested fix
Rebuilding the whole API model on a template edit would work but is the expensive path (the assemblies are re-read). The navigation is the only part of the state that reads the templates, so a cheaper fix is to key the GlobalsFor memo, or the value it is derived from, on menuStamps as well, and to do the same for the menu rendered into the API pages.
Found while restyling the Fantomas sidebar together with Claude Code.
What happens
With custom menu templates (
_menu_template.htmland_menu-item_template.htmlin the input folder), editing one of them whilefsdocs watchis running updates the documentation sections of the menu but not the API Reference section. That section keeps rendering with the template as it was when the watch started, until an assembly changes or the watch is restarted.Reproduction
fsdocs watchon a site that has both menu templates and API docs (Fantomas is one: https://github.com/fsprojects/fantomas/tree/main/docs)._menu_template.html, for example change the size of the chevron icon in the header.End-usersandContributorsheaders show the new markup, theAPI Referenceheader still shows the old one.Observed with 23.0.0-alpha.3.
fsdocs buildrenders both alike, so this is watch only.Cause
src/fsdocs-tool/DevServer.fs:menuStampstracks the menu templates and feedsnavInputs, so the documentation navigation is recomputed on an edit. That is why the docs sections do update.apiStateisAVal.map2over the assembly stamps and the crack result only. A menu template edit does not invalidate it, sofsdocs-list-of-namespacesis served from the state built at startup.buildApi,GlobalsFormemoises the navigation HTML per page root in aConcurrentDictionary, so even a fresh call into the same state returns the text rendered from the old template.The API reference pages themselves carry the same menu and have the same problem.
Suggested fix
Rebuilding the whole API model on a template edit would work but is the expensive path (the assemblies are re-read). The navigation is the only part of the state that reads the templates, so a cheaper fix is to key the
GlobalsFormemo, or the value it is derived from, onmenuStampsas well, and to do the same for the menu rendered into the API pages.Found while restyling the Fantomas sidebar together with Claude Code.