Docs are a bit messy about how app.html.heex becomes the default controller layout.

[DN4Davi]

I'm learning Phoenix by reading the documentation, and I found that the explanation of how app.html.heex becomes the default controller layout is a bit messy.

In the Routing section, the documentation explains how root.html.heex becomes the default router layout in the browser pipeline—nice. Then, we realize that even though app.html.heex isn't invoked in root.html.heex, it is included in all final HTMLs that don't explicitly reject it. Naturally, we assume this should be explained in the Controllers section—but it's not even mentioned there.

Next, we check Phoenix.Controller, but we don't have much luck, except for a contextless mention. Eventually, we find a comment in layouts.ex that states: "The 'app' layout is set as the default layout on both use HelloWeb, :controller {...}." Then, we look at :controller, only to find that it merely defines where controllers should look for HTML layouts—without explaining that the default behavior is to use app.html.heex for a given module.

[josevalim]

We will look into this but I just want to thank you for posting feedback on the docs. ❤️

[SteffenDE]

We added some clarifications to the docs and also changed the defaults to be more explicit. See #6090. If you have any more suggestions, please let us know! Thank you!