docs(layouts): rework the layout section, add default layout #5118
Conversation
✅ Deploy Preview for nuxt3-docs ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
There was a problem hiding this comment.
What do you think about condensing the examples down to:
- Layouts without pages
- Layouts with pages
- Manual control
- Changing layout dynamically
I don't think we need separate examples of how to use the default layout if we cover it within the first two examples.
| @@ -8,53 +8,72 @@ head.title: Layouts directory | |||
|
|
|||
| Nuxt provides a customizable layouts framework you can use throughout your application, ideal for extracting common UI or code patterns into reusable layout components. | |||
|
|
|||
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |||
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata or via the default layout `~/layouts/default.vue` (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |||
There was a problem hiding this comment.
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata or via the default layout `~/layouts/default.vue` (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |
| If you do not set a layout explicitly, then `~/layouts/default.vue` will be used. |
There was a problem hiding this comment.
What would be an example for multiple Layouts without pages that is not better done by adapting the app.vue?
- A "dark/light mode" is more of a CSS thing.
- A simple menu is better done within the app.vue.
- A login button I rather see in the app.vue
- A Logo is also better to keep it simple and in the app.vue
- A massive complex layout is better split into multiple components anyhow
The only reasonable thing I can come up with is something like:
- two different menus for the same content, i.e. "top aligned menu" vs "sidebar"
I'd say that's a pretty niche thing, and technically you still could do it better with CSS-grid! So If I am not mistaken I'd say Layouts almost always mean you are using pages already. If I am mistaken please tell me. But if I am right I rather put that first and make a note, towards the end of the page, about how you could do it, if you are not using pages.
Considering that I would rework it to:
Default Layout -> cause it is the easiest way to get in
Multiple Layouts -> cause that's the next likely thing
Layouts without pages -> cause now we covered the basics and the reader does not get confused if we introduce new concepts
Changing layout dynamically -> I think this first as it is more likely to be needed in my opinion but I am fine swapping it with the last
Manual control -> This feels more like abusing the system and should only be done with proper care maybe even add a warning or at least formulate it as a "technical possibility" and less like an "actual option" an expert can ignore it anyway
Maybe the question, in general, is what are layouts for? Cause technically you can use it in various ways. You could even recreate them with components. But why should we use layouts over that? I don't know the answer on a board Nuxt level. I think layouts are nice to get rid of code duplication and have a proper space for it that is different from components. But honestly, that feels still like a bit of a wishy-washy answer. So if you know maybe you can enlighten me.
Sorry for the wall of Text :)
There was a problem hiding this comment.
I think it is fair to say we can always replace Layouts with Wrapper dynamic components.
Main point of not using pages/ is to have our own non traditional routing. Imagine a small single page dashboard that has a login state. We can leverage default and guest layouts (or default and dashboard) that are automatically switched based on authentication state rather than page route.
| @@ -8,53 +8,72 @@ head.title: Layouts directory | |||
|
|
|||
| Nuxt provides a customizable layouts framework you can use throughout your application, ideal for extracting common UI or code patterns into reusable layout components. | |||
|
|
|||
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |||
| Layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. Layouts are used by setting a `layout` property as part of your page metadata or via the default layout `~/layouts/default.vue` (if you are using the `~/pages` integration), or by using the `<NuxtLayout>` component. | |||
There was a problem hiding this comment.
I think it is fair to say we can always replace Layouts with Wrapper dynamic components.
Main point of not using pages/ is to have our own non traditional routing. Imagine a small single page dashboard that has a login state. We can leverage default and guest layouts (or default and dashboard) that are automatically switched based on authentication state rather than page route.
| ``` | ||
|
|
||
| In your layout files, you'll need to use `<slot />` to define where the content of your layout will be loaded. For example: |
There was a problem hiding this comment.
Explaining about <slot /> was nice why you think should be removed here?
| </NuxtLayout> | ||
| </template> | ||
| ``` | ||
|
|
||
| ## Example: setting the layout with `~/pages` | ||
| ## Example: setting another layout |
There was a problem hiding this comment.
Since we started with two with/without pages variants, it was making sense to emphasis this section also applies to usage with pages.
Otherwise we might move using layouts without pages, to the last and assume the rest are using pages to simplify section.
* remove the section that explains how to use app.vue cause the example does not work * rework the layout section and prioritise the default layout to give the "least config example" first. * reword some other sections to reflect changes. * add a dynamically to the last section that helps better understand the content of that section
|
I agree with you on most things and really like your example! If that's how it is supposed to be done then I concur. I have updated it to reflect your comments:
Enjoy reviewing :) |
|
Will this be merged or do I have to do something? |
|
Thanks for working on it @Xanlantos @danielroe |
🔗 Linked issue
❓ Type of change
📚 Description
The default layout was missing and the documentation could be simplified by adding it. See commit msg for a detailed change list. I hope to be of help, but I have never contributed to Nuxt or any other public project. Please feel free to guide me.
📝 Checklist