Explicit explanation of site block address matching functionality in Caddyfiles

In learning Caddyfile syntax, I attempted this site block at the top of the Caddyfile...

https:// {
    tls mycert.pem mykey.pem {
        [...]
    }
}

...and saw that it "worked": my other site blocks appeared to inherit the certificate and key. This led me to believe that:

1. any directive I were to add would either take precedence, since I had defined it first in the Caddyfile and it was being executed first; or
2. the block was acting as a default/fallback to other more specific blocks, as I had seen in my searches that the length of matchers influenced their order, so it would make sense that that functionality would carry over to site blocks.

But it appears neither of those situations are actually the case, and when I added header directives to this block, I spent many frustrating minutes trying to decipher why it wouldn't apply those headers to any site.

Turns out the certificates were being used because they were loaded into the certificate cache by the site block, not because the block was being selected or used as a fallback; it just so happened that the certificate I brought with me to Caddy already had SANs for every domain name I was using, and all the other site blocks were pulling it in since they could use it, and did not have any TLS settings of their own defined, right?

As far as I can see, every route from an adapted Caddyfile will have terminal: true, and routes without matchers (e.g. https://) will be inserted last, well after the other site blocks that execute and terminate the chain before it. So the only way the above example site block would ever match is if no other block did.

I think it would be beneficial in the documentation to explain somewhere/make more explicit where necessary:

• how site blocks are ordered during adaptation, like how directives are ordered;
• that adapted site blocks are not cascading and terminate after the first match;
• that site blocks will automatically look in the cache for a certificate that matches their address; and
• that the idea of having defaults for certain values, e.g. headers and certificates, are not best approached via site blocks.

I have since manually edited the adapted output of my Caddyfile to get the kind of functionality I want: a matcherless route that did not terminate, to have a set of default headers applied to all the following routes. Maybe this could be an improvement to look into for Caddyfiles, where the closest working method is currently to create a snippet and import it into every site block.

...And if there is a way to do this that I haven't discovered yet, I'd love to hear about it.

Start by reviewing the Caddyfile documentation and the adapted output behavior described in the issue, focusing on site block ordering, termination, and certificate cache lookup. Done means the documentation clearly explains these behaviors and directs readers toward the supported way to apply shared defaults such as headers.