Skip to content

Commit

Permalink
clarify file conventions and layouts (#3898)
Browse files Browse the repository at this point in the history
  • Loading branch information
mayank99 authored Jul 28, 2023
1 parent 3d98a47 commit 577ca11
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 4 deletions.
6 changes: 3 additions & 3 deletions src/content/docs/en/core-concepts/layouts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ We conventionally use the term "layout" for Astro components that provide common

But, there is nothing special about a layout component! They can [accept props](/en/core-concepts/astro-components/#component-props) and [import and use other components](/en/core-concepts/astro-components/#component-structure) like any other Astro component. They can include [UI frameworks components](/en/core-concepts/framework-components/) and [client-side scripts](/en/guides/client-side-scripts/). They do not even have to provide a full page shell, and can instead be used as partial UI templates.

Layout components are commonly placed in a `src/layouts` directory in your project for organization, but this is not a requirement.
Layout components are commonly placed in a `src/layouts` directory in your project for organization, but this is not a requirement; you can choose to place them anywhere in your project. You can even colocate layout components alongside your pages by [prefixing the layout names with `_`](/en/core-concepts/routing/#excluding-pages).

## Sample Layout

Expand Down Expand Up @@ -251,9 +251,9 @@ const { title } = Astro.props.frontmatter || Astro.props;

## Nesting Layouts

Layout components do not need to contain an entire page worth of HTML. You can break your layouts into smaller components, and combine layout components to create even more flexible, page templates.
Layout components do not need to contain an entire page worth of HTML. You can break your layouts into smaller components, and combine layout components to create even more flexible, page templates. This pattern is useful when you want to share some code across multiple layouts.

For example, a `BlogPostLayout.astro` layout component could style a post's title, date and author. Then, a site-wide `BaseLayout.astro` could handle the rest of your page template, like navigation and footers. You can also pass props received from your post to another layout, just like any other nested component.
For example, a `BlogPostLayout.astro` layout component could style a post's title, date and author. Then, a site-wide `BaseLayout.astro` could handle the rest of your page template, like navigation, footers, SEO meta tags, global styles, and fonts. You can also pass props received from your post to another layout, just like any other nested component.

```astro {3} /</?BaseLayout>/ /</?BaseLayout url={frontmatter.url}>/
---
Expand Down
6 changes: 5 additions & 1 deletion src/content/docs/en/core-concepts/project-structure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ Astro processes, optimizes, and bundles your `src/` files to create the final we

Some files (like Astro components) are not even sent to the browser as written but are instead rendered to static HTML. Other files (like CSS) are sent to the browser but may be optimized or bundled with other CSS files for performance.

:::tip
While this guide describes some popular conventions used in the Astro community, the only directories reserved by Astro are `src/pages/` and `src/content/`. You are free to rename and reorganize any other directories in a way that works best for you.
:::

### `src/assets`

The [`src/assets`](/en/guides/assets/) directory is the recommended folder to use for storing assets (e.g. images) that are processed by Astro. This is not required, and this is not a special reserved folder.
Expand All @@ -78,7 +82,7 @@ The `src/content/` directory is reserved to store [content collections](/en/guid

### `src/layouts`

[Layouts](/en/core-concepts/layouts/) are a special kind of component that wrap some content in a larger page layout. These are most often used by [Astro pages](/en/core-concepts/astro-pages/) and [Markdown or MDX pages](/en/guides/markdown-content/) to define the layout of the page.
[Layouts](/en/core-concepts/layouts/) are Astro components that define the UI structure shared by one or more [pages](/en/core-concepts/astro-pages/).

Just like `src/components`, this directory is a common convention but not required.

Expand Down

0 comments on commit 577ca11

Please sign in to comment.