As many others have mentioned, the comment about AI failing to cough up good answers is intriguing. But what has not been said is that this may also be evidence that the HTMX documentation needs improvement. In particular it needs (many) more examples.
I have always been a reader of documentation for libraries that I use, and I have nearly always felt that docs could be better. Having tried to write docs myself, I know how hard (impossible?) it is to imagine not knowing how the thing you are documenting works.
Recursivedoubts, please take this criticism as encouragement more than anything! I think HTMX is important both as a library and as a reality check against complexity.
There is something unnerving about the HTMX docs to me: over and over again, I read them, and I think, "ok got it, sounds straightforward" but then it turns out there is something slightly tricky that is hard to diagnose. I don't quite know why.
One thing that has gotten me a couple times is not being clear on whether an attribute is for the request or response. I feel kind of dumb admitting this but it has been harder than I'd have thought. My best suggestion would be to add a request/response column in the attributes reference listings. Debug mode validation of "hx-*" attributes would be very welcome.
Early on I definitely mixed up hx-select-oob/hx-swap-oob and hx-include/hx-vals. I've also made mistakes with hx-indicator/htmx-indicator although that's a little different because one is a css class name.
Another that got me recently was trying to set an hx-on: after-settle handler in the target element (client side) and having nothing happen, but then discovering that if I put it in the response it would work. This made no sense at the time. Now I'm wondering if it was because the hx-swap was set to something other than innerHTML.
Anyway, I think the main point is that some of these things are sort of related in various subtle ways, and also sound similar, and are easy to mix up. As a new user, when I try to follow the directions and then apparently nothing happens, it is very hard to know how to proceed. Really the only way forward is to find a working example and try not to break it, or selectively break it to figure out how it works.
I know docs are a lot of work, but in an ideal future there would be example links to click on for each one of the attributes. Perhaps I could help with that at some point.
I've always thought that HTMX has amazing potential on the documentation front because one can build working examples that are served completely statically. In fact I can't think of a UI system that is more amenable to training an LLM. You would just need to write out the expected end-state of the HTML target.
For context, I've been using HTMX as crucial component of a back office web app for two years now. It is mostly a custom scheduling calendar. Most of it is simple HTMX, but I've used OOB-swap and hx-on in places. I use it to do fast state changes without full page refreshes, and to implement a few multi-step forms that require back-and forth of valid form choices. Recently I built a modal control with different edit actions, etc. I don't think I would have taken on this client at all if it weren't for HTMX. So, thank you!