Layouts
Layouts are Astro components used to provide a reusable UI structure, such as a page template.
We conventionally use the term “layout” for Astro components that provide common UI elements shared across pages such as headers, navigation bars, and footers. A typical Astro layout component provides Astro, Markdown or MDX pages with:
- a page shell (
<html>
,<head>
and<body>
tags) - a
<slot />
to specify where individual page content should be injected.
But, there is nothing special about a layout component! They can accept props and import and use other components like any other Astro component. They can include UI frameworks components and 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.
Sample Layout
Section titled Sample Layout📚 Learn more about slots.
Markdown/MDX Layouts
Section titled Markdown/MDX LayoutsPage layouts are especially useful for Markdown and MDX pages which otherwise would not have any page formatting.
Astro provides a special layout
frontmatter property to specify which .astro
component to use as the page layout.
A typical layout for Markdown or MDX pages includes:
- The
frontmatter
prop to access the Markdown or MDX page’s frontmatter and other data. - A default
<slot />
to indicate where the page’s Markdown/MDX content should be rendered.
You can set a layout’s Props
type with the MarkdownLayoutProps
or MDXLayoutProps
helper:
Markdown Layout Props
Section titled Markdown Layout PropsA Markdown/MDX layout will have access to the following information via Astro.props
:
file
- The absolute path of this file (e.g./home/user/projects/.../file.md
).url
- If it’s a page, the URL of the page (e.g./en/guides/markdown-content
).frontmatter
- all frontmatter from the Markdown or MDX document.frontmatter.file
- The same as the top-levelfile
property.frontmatter.url
- The same as the top-levelurl
property.
headings
- A list of headings (h1 -> h6
) in the Markdown or MDX document with associated metadata. This list follows the type:{ depth: number; slug: string; text: string }[]
.- (Markdown only)
rawContent()
- A function that returns the raw Markdown document as a string. - (Markdown only)
compiledContent()
- A function that returns the Markdown document compiled to an HTML string.
An example Markdown blog post may pass the following Astro.props
object to its layout:
Importing Layouts Manually (MDX)
Section titled Importing Layouts Manually (MDX)You may need to pass information to your MDX layout that does not (or cannot) exist in your frontmatter. In this case, you can instead import and use a <Layout />
component and pass it props like any other component:
Then, your values are available to you through Astro.props
in your layout, and your MDX content will be injected into the page where your <slot />
component is written:
📚 Learn more about Astro’s Markdown and MDX support in our Markdown/MDX guide.
Using one Layout for .md
, .mdx
, and .astro
Section titled Using one Layout for .md, .mdx, and .astroA single Astro layout can be written to receive the frontmatter
object from .md
and .mdx
files, as well as any named props passed from .astro
files.
In the example below, the layout will display the page title either from an Astro component passing a title
attribute or from a frontmatter YAML title
property:
Nesting Layouts
Section titled Nesting LayoutsLayout 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.
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.