This probably sounds stupid, but the implied $PWD for the static file server in the Caddyfile tutorial [1] confused me for about 15m because I was trying to run it in Docker.

The common patterns [2] in the reference section shows a better example, but I assumed the reference was a detailed reference, not beginner docs.

So I would say convention / implied config is great once you know how everything works, but it’s awful when you’re trying to learn because you have no idea what’s actually happening. I think the getting started config would be much better if it showed the 5-10 things that most people would expect to see (protocol, port, www-dir, etc.) and then described the shorthand version where all of that’s implied. As is, I have to go look up what the defaults are for all those things and the time it takes is way, way more than I’ll ever save by having that config implied.

Have you ever seen a config file where everything is commented out, but shows every option and the default value? I love those configs.

1. https://caddyserver.com/docs/caddyfile-tutorial

2. https://caddyserver.com/docs/caddyfile/patterns