(Searched forums and website github but didn’t see any performance threads so starting new one)
I’ve been reading a lot of documentation lately as I continue to explore caddy and one frustrating thing which stands out to me is how slow the documentation loads.
This is especially felt when reading through multiple layers of documentation all at once since one experiences the slowness at every layer of json.
I finally am posting this after a particuarly bad experience with the following url: JSON Config Structure - Caddy Documentation which took 18s average over three loads (that I recorded).
I wonder if there aren’t any opportunities to improve things here:
Even though the content is fairly static there is no caching at all of the documentation pages which means even repeated refreshes take the same amount of time.
Until the docs load there is no indication that anything is happening or I should be waiting.
Instead, there’s an warning box for This module does not come with Caddy. except none of the placeholders are filled in (and it also shows up for built in modules…). Even after knowing about the loading times my first reaction is to think that the documentation doesn’t exist for slow pages after waiting 10 or more seconds!
If the underlying speed can’t be solved maybe at least some caching or UI affordance for the loading state could be added. (And to be fair the higher level http module (JSON Config Structure - Caddy Documentation) only takes around ~6s to load so it seems to be a resource dependant cost)
Honestly I wasn’t even sure how much people even used the JSON documentation. I guess it’s good that it’s useful.
The slowness is a known regression after some patches that fixed other bugs (correctness issues), so actually they’ve been improved. But in order to do it I had to remove some caching. Hopefully I’ll have some time to see if I can speed things up later, maybe add some caching back in.
(Things got a lot slower once I implemented strong versioning in the database.)
Sorry about the faux-warning during load, that should be easier to fix, maybe a loading indicator or something.
Speeding things up will take some effort, and I’m pretty deep into another aspect of the project at the moment – but if anyone wants to at least contribute a loading indicator (and hide that yellow warning box by default), the website front-end is open source here and I could definitely review a PR: GitHub - caddyserver/website: The Caddy website
I’m a little picky about loading indicators though It has to work well (smooth/graceful) and look good.
Since I started with a layer4 use case it meant json only from the beginning and still lots of json even after I moved to caddyfile adapt based workflow.
+1 to initial loading indicator fix if any of us can clear the bar for good UX.
Unfortunately no, because it’s quite database heavy; it uses the list of registered modules (which you can see here Download Caddy) and reflects on the code to generate the docs. The code for the API backend isn’t public at this time (because it’s kinda messy and unlikely to actually receive any community help in practice).
The docs are generated directly from the source code though, you could probably read the source to get all the info you need, just as easily – especially with editors that have features like “Click to go to definition” or “Show uses” or whatever.
It has to work well (smooth/graceful) and look good.