Template structure

This section is about the file structure. You will learn how the different files are organized, but most important of all, how to manage your project with Astro. Let's dive into the folder structure.

Global structure

root
├── public/
│   ├── img/
│   └── images/
│   └── svg/
├── src/
│   └── components/
│   │   ├── Component.astro
│   └── content/
│   │   ├── blog/
│   │   ├── pages/
│   │   ├── config.ts
│   ├── layouts/
│   │   ├── Base.astro
│   │   ├── Default.astro
│   ├── pages/
│   │   ├── index.astro
│   └── config.ts
└── .npmrc
├── astro.config.mjs
└── tailwind.config.cjs
└── package.json

The directory structure can seem unusual for someone who is not used to build tools. We will break each part of it, so you understand how everything works. You can learn more about Astro project structures on their documentation.

Static assets

root
├── public/
│   ├── img/
│   └── images/
│   └── svg/

Astro serves static assets like images, fonts or any type of supported files inside the /public folder. Use this folder to store your project images and any other kind of uncompiled assets that you need in your project.

Content folder

root
├── src/
│   └── content/

All your site content is and has to be stored inside the src/content folder. The different content types are then classified into sub-folders, like src/content/blog or src/content/pages. Each one of these sub-folders represents an Astro v2 concept called a collection.

A content collection is any directory inside the reserved src/content project directory, such as src/content/newsletter and src/content/blog. Only content collections are allowed inside the src/content directory. This directory cannot be used for anything else.

A content entry is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (.md) or MDX (.mdx) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.

There is another config.ts file that resides inside the src/content folder.This is a special file that Astro will automatically load and use to configure your content collections. This files contain schemas, that define and describe your collections (e.g in our case blog and pages).

Schemas enforce consistent frontmatter within a collection. A schema guarantees that your frontmatter exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know. Learn more about Astro content collections and schemas by reading the official documentation.

Layouts folder

root
├── src/
│   └── 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.

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.

The layouts folder holds all the template layouts. It is mandatory to have at least one layout, and it should always be named default.html. Additional layouts can have the names you want, but don't forget the .astro extension. Also notice the <slot /> tag that is present in each layout file. This is a reference to append the rest of the page content.

Using a layout in a page

The layouts/ folder can hold one or more layout files. But generally, you'll find one or two in there like Default.astro. Layouts are nothing more than Astro components. Inside a page like src/pages/index.astro, you can use a layout like this:

---
import Layout from '../layouts/Default.astro'
---
<Layout>
  <!-- Your page content goes in here -->
</Layout>

You can learn more about Astro layouts by reading their documentation.

Pages folder

root
├── src/
│   └── pages/

The pages folder holds all the template pages. Pages are focused on content. Pages are files that live in the src/pages/ sub-directory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website. You will sometimes find a particular statement at the top of Astro pages code :

---
import Layout from '../layouts/Default.astro'
import Navbar from '../components/Navbar.astro'
---

In each .astro file, you can open a special area between a --- and a ---. Inside that area, everything you write is treated and processed as javascript. You can import functions, components and declare variables.

Page files

Your project pages live in this folder. They all have a .astro extensions. Astro also support other types of files for pages. .astro, .md, .mdx and .html extensions are supported. You can learn more about Astro pages by reading their documentation.

Components folder

root
├── src/
│   └── components/

The components folder holds all your reusable HTML components. Components are chunks of code that you want to reuse as is across your application : it can be a button, a navbar, a content section or whatever you want. Note that you can create as many sub-folders as you want to organize your components. Components are named like page files, but in Camel case : Navbar.astro. When you want to call a component in one of your layouts or pages, you first need to import it:

---
import Navbar from '../components/Navbar.astro'
---

You can then use the component in your page like this:

<Layout>
  <Navbar />
</Layout>

Astro components behave like components from advanced frameworks like Vue and React. They can instantiate and use variables, define and use props, fetch data and many more things that make Astro such a complete and solid framework. You can learn more about Astro components by reading their documentation.

Root files

There also a few files sitting at the root of the project that we need to discuss before getting into serious business:

• astro.config.mjs : The main Astro configuration file.
• package.json : Lists all your project's dependencies and gives useful metadata.
• tailwind.config.cjs : The Tailwind CSS configuration file.