[waf]

I've used this before (as an API consumer, not an author), and while it's better than many other documentation sites, for some reason the "scrolling will change the URL and active navigation item" was really disorienting. I kept finding myself lost in the one long stream of documentation -- there was no anchor!

The goal is to have everything browser-searchable (i.e. ctrl-f), and I think it's a good goal. I wonder if there's a better way than having everything on a single page with very little compartmentalization, though.

[throwanem]

Since it's a static site, splitting the content across multiple pages and still being searchable would mean you'd need to push the whole search index down to the client and have the search operate locally. Not that it couldn't be done, and I can think of a few optimizations, but for the "very large docs" use case that's called out in the readme, it might still amount to a lot of data on top of the "a lot of data" that constitutes the docs themselves as rendered. Relying on browsers' built-in text search makes a lot of sense, especially to start with; I'd likewise wait to see a very strong use case before building out my own search to supersede it.

I don't know how I feel about the way they're managing the URL fragment. The way they're calling pushState, it adds history entries while scrolling, and that makes the back button behave nonintuitively; I think I'd rather see history entries created only when I click a header, or otherwise take some specific action to demonstrate the intent. That makes the back behavior easier to reason about, and also preserves the easy deep linkability that they are, imo rightly, going for.

[Aeolun]

If you load all the content from the start, you also push the entire index to the client.

It could even be faster because all the HTML markup can be left out for the search index.

[throwanem]

If you do it as separate static pages, though (per the upstream comment: "I wonder if there's a better way than having everything on a single page with very little compartmentalization...") then you're no longer pushing all the content to the client at once. That limits the scope of the browser's built-in search to the current page, and thus necessitates the additional complexity to regain support for searching over all the docs.