Difficulty finding information on "global variables"

[davenquinn]

Hello Caddy team,

I'm writing after spending about 15 minutes trying to decipher from the docs whether and how the {http.request.cookie.*} signature was actually available to me in a Caddyfile config. (it is!)

I spent a while trying to search for combinations of "global variables" and scan through the "Caddyfile concepts" docs to see where variables were mentioned. Once I realized that "Placeholders" was the preferred terminology, I was more able to find what I needed. However, this took a while. A few suggestions:

• Make "Placeholders" appear when "Variables" is searched
• Add a quick description next to each top-level list item in the "Caddyfile concepts" section. "Variables are called placeholders" is a meta-concept that shows up late.
• Consider adding the tables of placeholders (global, http-context-limited, etc...) to the "API" section of the docs – I was assuming these would be treated as reference information, but instead they're nested in the conceptual discussion, making them harder to find.

Thanks for all your hard work — the docs are quite fantastic overall and I hope my contribution and beginner's perspective is useful.

[francislavoie]

Thanks for the feedback!

Make "Placeholders" appear when "Variables" is searched

Actually, variables are a distinct concept from placeholders. See https://caddyserver.com/docs/caddyfile/directives/vars, variables are stored in the request context and can be pulled out using placeholders. So if we were to say something like "variables are placeholders", that would be even more confusing, I think.

That said, we don't have a lot of control over the search, since it's entirely generated using the Algolia Docsearch service. It mainly scans the page headers.

Consider adding the tables of placeholders (global, http-context-limited, etc...) to the "API" section of the docs

But placeholders don't have anything to do with the API. The API is specifically about the HTTP API via the admin endpoint.

We generally recommend to all users to read through the entire Caddyfile Concepts page, most of the key concepts, like placeholders, are covered there.

I do agree the Placeholders section on that page could use some more elaboration though, it's a bit terse.

[mholt]

Great feedback, thank you. The new docs will probably structure things differently and hopefully make them more discoverable/obvious.