Well, we're not talking about placeholders in that paragraph at all. It's just an explanation of Auto HTTPS.

I think for novices, having the :// in there makes it clearer what part of the URL we're talking about.

We're talking about site addresses there, and we're trying to reinforce the difference between example.com and http://example.com, and that difference is http://, not only http.

Where should the format of the scheme placeholder be documented?

Perhaps it would be better to use specific terms to mean the same thing consistently. Since scheme already means something that's constrained by an API guarantee, the word "protocol" could be used there to avoid confusion for people searching the page for scheme.

We can adjust it here https://caddyserver.com/docs/json/apps/http/#docs to mention "typically http or https".

I think that'll help. Does that make sense AJ?

I think what caddy needs is a man page - meaning a single, super long page that's easy to search by keyword.

There's just too many sources of information across too many official pages and guides.

Having each of the placeholders link to where the canonical source of information is would be really helpful.

I think just putting all the placeholders examples in the same place with the documentation about them would be most useful.

Presently, the placeholders guide essentially says "there are more, but once you get used to it you can just guess", but... it's really not intuitive.

Alternatively, having a specific placeholders section to each module would be more helpful.

But there's also the problem of the canonical location of the information.

It seems like the Caddyfile is what people are going to write by hand, so that's where it should be.

All SEO almost exclusively goes to the Caddyfile docs.

If the JSON is canonical then the Caddyfile section should be moved into the JSON section, and redirects should be put in place to preserve the SEO.

the Go philosophy is to organize by Package ("what problem does the solve?"), but these docs are mostly organized by Taxonomy ("What is the classification of the parts of the thing?").

Matchers / Placholders are the special case, just like HTTP routing, that makes sense to place all together - it's the index to the rest of all the things, but the the functionality should be grouped together. But if I'm looking for info on basicauth, it makes sense to group the Caddyfile, json, placeholders, and QuickStart examples all in the one place I'm looking at for basicauth rather than in a JSON section, a Caddyfile section, a Wiki section, user clarifications in the forums, and perhaps a special note in another official section.

If there were a single page view or an undiscriminating search, that would be a great stopgap.

Placing it in the JSON section is the least useful section, because I've come to learn that 9 times out of 10 it will be more clear out to configure something with the caddy file and then adapt it to JSON and denest it than to try to read the JSON docs directly, because many of them are missing, or link to an empty object, but I may go back to the JSON section because occasionally there's a property there that isn't exposed in the Caddyfile.