Day15 - Astro Series: Layout

@ Astro

A beautiful gradient background with a heading: "Basic Layout"

Introduction

Previously you learned how to write pages using Markdown and MDX. In this chapter you’ll learn how to set up layouts for those files. Think of layouts as templates for common page structures — defining layout pages can save repetition and centralize page management.

What is a Layout

As mentioned earlier, it’s common to create a src/layouts folder to store layout-related .astro components — you can name it whatever you like. So what are layout-specific components for? Creating a folder to organize these types of components is a common pattern for managing pages. Layout components can accept injected content via <slot/>.

In the earlier styles chapter we practiced using <slot/> to create a <Base> component — that’s a typical layout component.

Layouts for Markdown and MDX

Markdown or MDX files are usually rendered through layout components, and Astro provides a special layout Frontmatter property to specify the layout component to use for that file.

---
layout: ../layouts/BaseLayout.astro
subHeadline: 'HelloWorld!'
author: 'Joe Doe'
date: '27 Sep 2023'
---


All Frontmatter properties can be accessed in Astro components.


The `layout` property is a property specific to Astro.


It can be used to specify the layout of Markdown and MDX components located in `src/pages`.
---
// `src/layout/BaseLayout.astro`
// Deconstructing Frontmatter data
const { frontmatter } = Astro.props;
---


<html>
  <head>
    <title>{frontmatter.title}</title>
  </head>
  <body>
    <h1>{frontmatter.title} by {frontmatter.author}</h1>
    <!-- The rendered HTML will be injected into the slot -->
    <slot />
    <p>Written on: {frontmatter.date}</p>
  </body>
</html>

You can also use the provided helpers to define Props (MarkdownLayoutProps or MDXLayoutProps):

import type { MarkdownLayoutProps } from 'astro';


type Props = MarkdownLayoutProps<{
  // Define frontmatter props here.
  title: string,
  author: string,
  date: string,
}>;

Below is an example of the data a Markdown/MDX layout can access via Astro.props:

Astro.props = {
  file: '/home/user/projects/.../file.md',
  url: '/en/guides/markdown-content/',
  frontmatter: {
    title: 'Astro 0.18 Release',
    date: 'Tuesday, July 27 2021',
    author: 'Matthew Phillips',
    description: 'Astro 0.18 is our biggest release since Astro launch.',
    file: '/home/user/projects/.../file.md',
    url: '/en/guides/markdown-content/',
  },
  headings: [
    {
      depth: 1,
      text: 'Astro 0.18 Release',
      slug: 'astro-018-release',
    },
    {
      depth: 2,
      text: 'Responsive partial hydration',
      slug: 'responsive-partial-hydration',
    },
  ],
  rawContent: () => '# Astro 0.18 Release\nA little over a month ago, the first public beta [...]',
  compiledContent: () => '<h1>Astro 0.18 Release</h1>\n<p>A little over a month ago, the first public beta [...]</p>',
};

You can access Markdown frontmatter, file location URLs, headings within the content, and the rendered HTML, among other things.

Summary

Using the layout Frontmatter in Markdown or MDX lets you quickly specify which component layout to use for content. Of course, you can also manually import the desired layout component into MDX and place it where you want. It’s not mandatory — there are other ways to assign layouts to Markdown files, which we’ll cover in the next chapter.

Finally, it’s recommended to practice hands-on. If you run into issues, you can check out my example🔗:

  • Write a Markdown file and specify its layout.
  • Create an ArticleLayout.astro component and use the Props-provided title information to render a Table of Contents for a Markdown article.

Further Reading