메뉴
Full developer documentation for Astro
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | Astro Docs |
| description | Full developer documentation for Astro |
Astro is the web framework for building content-driven websites like blogs, marketing, and e-commerce. Learn why Astro might be a good choice for your next website.
Astro is the web framework for building content-driven websites like blogs, marketing, and e-commerce. Astro is best-known for pioneering a new frontend architecture to reduce JavaScript overhead and complexity compared to other frameworks. If you need a website that loads fast and has great SEO, then Astro is for you.
Astro is an all-in-one web framework. It includes everything you need to create a website, built-in. There are also hundreds of different integrations and API hooks available to customize a project to your exact use case and needs.
Some highlights include:
Section titled “Design Principles”
Here are five core design principles to help explain why we built Astro, the problems that it exists to solve, and why Astro may be the best choice for your project or team.
Astro is…
Section titled “Content-driven”
Astro was designed for building content-rich websites. This includes marketing sites, publishing sites, documentation sites, blogs, portfolios, landing pages, community sites, and e-commerce sites. If you have content to show, it needs to reach your reader quickly.
By contrast, most modern web frameworks were designed for building web applications. These frameworks excel at building more complex, application-like experiences in the browser: logged-in admin dashboards, inboxes, social networks, todo lists, and even native-like applications like Figma and Ping. However with that complexity, they can struggle to provide great performance when delivering your content.
Astro’s focus on content from its beginnings as a static site builder have allowed Astro to sensibly scale up to performant, powerful, dynamic web applications that still respect your content and your audience. Astro’s unique focus on content lets Astro make tradeoffs and deliver unmatched performance features that wouldn’t make sense for more application-focused web frameworks to implement.
Astro leverages server rendering over client-side rendering in the browser as much as possible. This is the same approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But you don’t need to learn a second server-side language to unlock it. With Astro, everything is still just HTML, CSS, and JavaScript (or TypeScript, if you prefer).
This approach stands in contrast to other modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks were built for client-side rendering of your entire website and include server-side rendering mainly to address performance concerns. This approach has been dubbed the Single-Page App (SPA), in contrast with Astro’s Multi-Page App (MPA) approach.
The SPA model has its benefits. However, these come at the expense of additional complexity and performance tradeoffs. These tradeoffs harm page performance -- critical metrics like Time to Interactive (TTI) -- which doesn’t make much sense for content-focused websites where first-load performance is essential.
Astro’s server-first approach allows you to opt in to client-side rendering only if, and exactly as, necessary. You can choose to add UI framework components that run on the client. You can take advantage of Astro’s view transitions router for finer control over select page transitions and animations. Astro’s server-first rendering, either pre-rendered or on-demand, provides performant defaults that you can enhance and extend.
Section titled “Fast by default”
Good performance is always important, but it is especially critical for websites whose success depends on displaying your content. It has been well-proven that poor performance loses you engagement, conversions, and money. For example:
In many web frameworks, it is easy to build a website that looks great during development only to load painfully slow once deployed. JavaScript is often the culprit, since many phones and lower-powered devices rarely match the speed of a developer’s laptop.
Astro’s magic is in how it combines the two values explained above -- a content focus with a server-first architecture -- to make tradeoffs and deliver features that other frameworks cannot. The result is amazing web performance for every website, out of the box. Our goal: It should be nearly impossible to build a slow website with Astro.
An Astro website can load 40% faster with 90% less JavaScript than the same site built with the most popular React web framework. But don’t take our word for it: watch Astro’s performance leave Ryan Carniato (creator of Solid.js and Marko) speechless.
Astro’s goal is to be accessible to every web developer. Astro was designed to feel familiar and approachable regardless of skill level or past experience with web development.
The .astro UI language is a superset of HTML: any valid HTML is valid Astro templating syntax! So, if you can write HTML, you can write Astro components! But, it also combines some of our favorite features borrowed from other component languages like JSX expressions (React) and CSS scoping by default (Svelte and Vue). This closeness to HTML also makes it easier to use progressive enhancement and common accessibility patterns without any overhead.
We then made sure that you could also use your favorite UI component languages that you already know, and even reuse components you might already have. React, Preact, Svelte, Vue, Solid, and others, including web components, are all supported for authoring UI components in an Astro project.
Astro was designed to be less complex than other UI frameworks and languages. One big reason for this is that Astro was designed to render on the server, not in the browser. That means that you don’t need to worry about hooks (React), stale closures (also React), refs (Vue), observables (Svelte), atoms, selectors, reactions, or derivations. There is no reactivity on the server, so all of that complexity melts away.
One of our favorite sayings is opt in to complexity. We designed Astro to remove as much “required complexity” as possible from the developer experience, especially as you onboard for the first time. You can build a “Hello World” example website in Astro with just HTML and CSS. Then, when you need to build something more powerful, you can incrementally reach for new features and APIs as you go.
Section titled “Developer-focused”
We strongly believe that Astro is only a successful project if people love using it. Astro has everything you need to support you as you build with Astro.
Astro invests in developer tools like a great CLI experience from the moment you open your terminal, an official VS Code extension for syntax highlighting, TypeScript and Intellisense, and documentation actively maintained by hundreds of community contributors and available in 14 languages.
Our welcoming, respectful, inclusive community on Discord is ready to provide support, motivation, and encouragement. Open a #support thread to get help with your project. Visit our dedicated #showcase channel for sharing your Astro sites, blog posts, videos, and even work-in-progress for safe feedback and constructive criticism. Participate in regular live events such as our weekly community call, “Talking and Doc’ing,” and API/bug bashes.
As an open-source project, we welcome contributions of all types and sizes from community members of all experience levels. You are invited to join in roadmap discussions to shape the future of Astro, and we hope you’ll contribute fixes and features to the core codebase, compiler, docs, language tools, websites, and other projects.
Learn about how Astro's islands architecture helps keep sites fast.
Astro helped pioneer and popularize a new frontend architecture pattern called Islands Architecture. Islands architecture works by rendering the majority of your page to fast, static HTML with smaller “islands” of JavaScript added when interactivity or personalization is needed on the page (an image carousel, for example). This avoids the monolithic JavaScript payloads that slow down the responsiveness of many other, modern JavaScript web frameworks.
Section titled “A brief history”
The term “component island” was first coined by Etsy’s frontend architect Katie Sylor-Miller in 2019. This idea was then expanded on and documented in this post by Preact creator Jason Miller on August 11, 2020.
The general idea of an “Islands” architecture is deceptively simple: render HTML pages on the server, and inject placeholders or slots around highly dynamic regions […] that can then be “hydrated” on the client into small self-contained widgets, reusing their server-rendered initial HTML.
— Jason Miller, Creator of Preact
The technique that this architectural pattern builds on is also known as partial or selective hydration.
In contrast, most JavaScript-based web frameworks hydrate & render an entire website as one large JavaScript application (also known as a single-page application, or SPA). SPAs provide simplicity and power but suffer from page-load performance problems due to heavy client-side JavaScript usage.
SPAs have their place, even embedded inside an Astro page. But, SPAs lack the native ability to selectively and strategically hydrate, making them a heavy-handed choice for most projects on the web today.
Astro became popular as the first mainstream JavaScript web framework with selective hydration built-in, using that same component islands pattern first coined by Sylor-Miller. We’ve since expanded and evolved on Sylor-Miller’s original work, which helped to inspire a similar component island approach to dynamically server-rendered content.
Section titled “What is an island?”
In Astro, an island is an enhanced UI component on an otherwise static page of HTML.
A client island is an interactive JavaScript UI component that is hydrated separately from the rest of the page, while a server island is a UI component that server-renders its dynamic content separately from the rest of the page.
Both islands run expensive or slower processes independently, on a per-component basis, for optimized page loads.
Section titled “Island components”
Astro components are the building blocks of your page template. They render to static HTML with no client-side runtime.
Think of a client island as an interactive widget floating in a sea of otherwise static, lightweight, server-rendered HTML. Server islands can be added for personalized or dynamic server-rendered elements, such as a logged in visitor’s profile picture.
Header (interactive island)
Sidebar (static HTML)
Static content like text, images, etc.
Image carousel (interactive island)
Footer (static HTML)
Source: Islands Architecture: Jason Miller
An island always runs in isolation from other islands on the page, and multiple islands can exist on a page. Client islands can still share state and communicate with each other, even though they run in different component contexts.
This flexibility allows Astro to support multiple UI frameworks like React, Preact, Svelte, Vue, and SolidJS. Because they are independent, you can even mix several frameworks on each page.
Tip
Although most developers will stick to just one UI framework, Astro supports multiple frameworks in the same project. This allows you to:
Section titled “Client Islands”
By default, Astro will automatically render every UI component to just HTML & CSS, stripping out all client-side JavaScript automatically.
src/pages/index.astro
<MyReactComponent />
This may sound strict, but this behavior is what keeps Astro websites fast by default and protects developers from accidentally sending unnecessary or unwanted JavaScript that might slow down their website.
Turning any static UI component into an interactive island requires only a client:* directive. Astro then automatically builds and bundles your client-side JavaScript for optimized performance.
src/pages/index.astro
<!-- This component is now interactive on the page!
The rest of your website remains static. -->
<MyReactComponent client:load />
With islands, client-side JavaScript is only loaded for the explicit interactive components that you mark using client:* directives.
And because interaction is configured at the component-level, you can handle different loading priorities for each component based on its usage. For example, client:idle tells a component to load when the browser becomes idle, and client:visible tells a component to load only once it enters the viewport.
The most obvious benefit of building with Astro Islands is performance: the majority of your website is converted to fast, static HTML and JavaScript is only loaded for the individual components that need it. JavaScript is one of the slowest assets that you can load per-byte, so every byte counts.
Another benefit is parallel loading. In the example illustration above, the low-priority “image carousel” island doesn’t need to block the high-priority “header” island. The two load in parallel and hydrate in isolation, meaning that the header becomes interactive immediately without having to wait for the heavier carousel lower down the page.
Even better, you can tell Astro exactly how and when to render each component. If that image carousel is really expensive to load, you can attach a special client directive that tells Astro to only load the carousel when it becomes visible on the page. If the user never sees it, it never loads.
In Astro, it’s up to you as the developer to explicitly tell Astro which components on the page need to also run in the browser. Astro will only hydrate exactly what’s needed on the page and leave the rest of your site as static HTML.
Client islands are the secret to Astro’s fast-by-default performance story!
Read more about using JavaScript framework components in your project.
Section titled “Server islands”
Server islands are a way to move expensive or slow server-side code out of the way of the main rendering process, making it easy to combine high-performance static HTML and dynamic server-generated components.
Add the server:defer directive to any Astro component on your page to turn it into its own server island:
src/pages/index.astro
---
import Avatar from "../components/Avatar.astro";
---
<Avatar server:defer />
This breaks up your page with smaller areas of server-rendered content that each load in parallel.
Your page’s main content can be rendered immediately with placeholder content, such as a generic avatar until your island’s own content is available. With server islands, having small components of personalized content does not delay the rendering of an otherwise static page.
This rendering pattern was built to be portable. It does not depend on any server infrastructure so it will work with any host, from a Node.js server in a Docker container to the serverless provider of your choice.
One benefit of server islands is the ability to render the more highly dynamic parts of your page on the fly. This allows the outer shell and main content to be more aggressively cached, providing faster performance.
Another benefit is providing a great visitor experience. Server islands are optimized and load quickly, often even before the browser has even painted the page. But in the short time it takes for your islands to render, you can display custom fallback content and prevent any layout shift.
An example of a site that benefits from Astro’s server islands is an e-commerce storefront. Although the main content of product pages change infrequently, these pages typically have some dynamic pieces:
Using server islands for these elements, your visitor will see the most important part of the page, your product, immediately. Generic avatars, loading spinners, and store announcements can be displayed as fallback content until the personalized parts are available.
Read more about using server islands in your project.
How to install Astro and start a new project.
The create astro CLI command is the fastest way to start a new Astro project from scratch. It will walk you through every step of setting up your new Astro project and allow you to choose from a few different official starter templates.
You can also run the CLI command with the template flag to begin your project using any existing theme or starter template. Explore our themes and starters showcase where you can browse themes for blogs, portfolios, documentation sites, landing pages, and more!
To install Astro manually instead, see our step-by-step manual installation guide.
Online previews
Prefer to try Astro in your browser? Visit astro.new to browse our starter templates and spin up a new Astro project without ever leaving your browser.
Section titled “Prerequisites”
v18.20.8 or v20.3.0, v22.0.0 or higher. (v19 and v21 are not supported.)Section titled “Browser compatibility”
Astro is built with Vite which targets browsers with modern JavaScript support by default. For a complete reference, you can see the list of currently supported browser versions in Vite.
Section titled “Install from the CLI wizard”
You can run create astro anywhere on your machine, so there’s no need to create a new empty directory for your project before you begin. If you don’t have an empty directory yet for your new project, the wizard will help create one for you automatically.
Run the following command in your terminal to start the install wizard:
npm
# create a new project with npm
npm create astro@latest
pnpm
# create a new project with pnpm
pnpm create astro@latest
Yarn
# create a new project with yarn
yarn create astro
If all goes well, you will see a success message followed by some recommended next steps.
Now that your project has been created, you can cd into your new project directory to begin using Astro.
If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing.
npm
npm install
pnpm
pnpm install
Yarn
yarn install
You can now start the Astro dev server and see a live preview of your project while you build!
Section titled “CLI installation flags”
You can run the create astro command with additional flags to customize the setup process (e.g. answering “yes” to all questions, skipping the Houston animation) or your new project (e.g. install git or not, add integrations).
See all the available create astro command flags.
Section titled “Add integrations”
You can start a new Astro project and install any official integrations or community integrations that support the astro add command at the same time by passing the --add argument to the create astro command.
Run the following command in your terminal, substituting any integration that supports the astro add command:
npm
# create a new project with React and Partytown
npm create astro@latest -- --add react --add partytown
pnpm
# create a new project with React and Partytown
pnpm create astro@latest --add react --add partytown
Yarn
# create a new project with React and Partytown
yarn create astro --add react --add partytown
Section titled “Use a theme or starter template”
You can start a new Astro project based on an official example or the main branch of any GitHub repository by passing a --template argument to the create astro command.
Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use:
npm
# create a new project with an official example
npm create astro@latest -- --template <example-name>
# create a new project based on a GitHub repository’s main branch
npm create astro@latest -- --template <github-username>/<github-repo>
pnpm
# create a new project with an official example
pnpm create astro@latest --template <example-name>
# create a new project based on a GitHub repository’s main branch
pnpm create astro@latest --template <github-username>/<github-repo>
Yarn
# create a new project with an official example
yarn create astro --template <example-name>
# create a new project based on a GitHub repository’s main branch
yarn create astro --template <github-username>/<github-repo>
By default, this command will use the template repository’s main branch. To use a different branch name, pass it as part of the --template argument: <github-username>/<github-repo>#<branch>.
This guide will walk you through the steps to manually install and configure a new Astro project.
If you prefer not to use our automatic create astro CLI tool, you can set up your project yourself by following the guide below.
Create your directory
Create an empty directory with the name of your project, and then navigate into it.
mkdir my-astro-project
cd my-astro-project
Once you are in your new directory, create your project package.json file. This is how you will manage your project dependencies, including Astro. If you aren’t familiar with this file format, run the following command to create one.
npm
npm init --yes
pnpm
pnpm init
Yarn
yarn init --yes
Install Astro
First, install the Astro project dependencies inside your project.
Important
Astro must be installed locally, not globally. Make sure you are not running npm install -g astro pnpm add -g astro or yarn add global astro.
npm
npm install astro
pnpm
pnpm add astro
Yarn
yarn add astro
Then, replace any placeholder “scripts” section of your package.json with the following:
package.json
{
"scripts": {
-"test": "echo \"Error: no test specified\" && exit 1",
+"dev": "astro dev",
+"build": "astro build",
+"preview": "astro preview"
},
}
You’ll use these scripts later in the guide to start Astro and run its different commands.
Create your first page
In your text editor, create a new file in your directory at src/pages/index.astro. This will be your first Astro page in the project.
For this guide, copy and paste the following code snippet (including --- dashes) into your new file:
src/pages/index.astro
---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
some magic sprinkled in to help you build great templates. -->
<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>
<style>
h1 {
color: orange;
}
</style>
Create your first static asset
You will also want to create a public/ directory to store your static assets. Astro will always include these assets in your final build, so you can safely reference them from inside your component templates.
In your text editor, create a new file in your directory at public/robots.txt. robots.txt is a simple file that most sites will include to tell search bots like Google how to treat your site.
For this guide, copy and paste the following code snippet into your new file:
public/robots.txt
# Example: Allow all bots to scan and index your site.
# Full syntax: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
Create astro.config.mjs
Astro is configured using astro.config.mjs. This file is optional if you do not need to configure Astro, but you may wish to create it now.
Create astro.config.mjs at the root of your project, and copy the code below into it:
astro.config.mjs
import { defineConfig } from "astro/config";
// https://astro.build/config
export default defineConfig({});
If you want to include UI framework components such as React, Svelte, etc. or use other tools such as MDX or Partytown in your project, here is where you will manually import and configure integrations.
Read Astro’s API configuration reference for more information.
Add TypeScript support
TypeScript is configured using tsconfig.json. Even if you don’t write TypeScript code, this file is important so that tools like Astro and VS Code know how to understand your project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.
If you do intend to write TypeScript code, using Astro’s strict or strictest template is recommended. You can view and compare the three template configurations at astro/tsconfigs/.
Create tsconfig.json at the root of your project, and copy the code below into it. (You can use base, strict, or strictest for your TypeScript template):
tsconfig.json
{
"extends": "astro/tsconfigs/base"
}
Read Astro’s TypeScript setup guide for more information.
Next Steps
If you have followed the steps above, your project directory should now look like this:
node_modules/
public/
src/
pages/
astro.config.mjs
package-lock.json or yarn.lock, pnpm-lock.yaml, etc.
package.json
tsconfig.json
You can now start the Astro dev server and see a live preview of your project while you build!
An introduction to the basic file structure of an Astro project.
Your new Astro project generated from the create astro CLI wizard already includes some files and folders. Others, you will create yourself and add to Astro’s existing file structure.
Here’s how an Astro project is organized, and some files you will find in your new project.
Section titled “Directories and Files”
Astro leverages an opinionated folder layout for your project. Every Astro project root should include the following directories and files:
src/* - Your project source code (components, pages, styles, images, etc.)public/* - Your non-code, unprocessed assets (fonts, icons, etc.)package.json - A project manifest.astro.config.mjs - An Astro configuration file. (recommended)tsconfig.json - A TypeScript configuration file. (recommended)Section titled “Example Project Tree”
A common Astro project directory might look like this:
public/
src/
blog/
components/
images/
layouts/
pages/
posts/
about.astro
index.astro
rss.xml.js
styles/
content.config.ts
astro.config.mjs
package.json
tsconfig.json
src/The src/ folder is where most of your project source code lives. This includes:
Astro processes, optimizes, and bundles your src/ files to create the final website that is shipped to the browser. Unlike the static public/ directory, your src/ files are built and handled for you by Astro.
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 directory reserved by Astro is src/pages/. You are free to rename and reorganize any other directories in a way that works best for you.
src/pagesPages routes are created for your site by adding supported file types to this directory.
Caution
src/pages is a required sub-directory in your Astro project. Without it, your site will have no pages or routes!
src/componentsSection titled “src/components”
Components are reusable units of code for your HTML pages. These could be Astro components, or UI framework components like React or Vue. It is common to group and organize all of your project components together in this folder.
This is a common convention in Astro projects, but it is not required. Feel free to organize your components however you like!
src/layoutsLayouts are Astro components that define the UI structure shared by one or more pages.
Just like src/components, this directory is a common convention but not required.
src/stylesIt is a common convention to store your CSS or Sass files in a src/styles directory, but this is not required. As long as your styles live somewhere in the src/ directory and are imported correctly, Astro will handle and optimize them.
public/The public/ directory is for files and assets in your project that do not need to be processed during Astro’s build process. The files in this folder will be copied into the build folder untouched, and then your site will be built.
This behavior makes public/ ideal for common assets that do not require any processing, like some images and fonts, or special files such as robots.txt and manifest.webmanifest.
You can place CSS and JavaScript in your public/ directory, but be aware that those files will not be bundled or optimized in your final build.
Tip
As a general rule, any CSS or JavaScript that you write yourself should live in your src/ directory.
package.jsonThis is a file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Astro (ex: npm run dev, npm run build).
There are two kinds of dependencies you can specify in a package.json: dependencies and devDependencies. In most cases, these work the same: Astro needs all dependencies at build time, and your package manager will install both. We recommend putting all of your dependencies in dependencies to start, and only use devDependencies if you find a specific need to do so.
For help creating a new package.json file for your project, check out the manual setup instructions.
astro.config.mjsSection titled “astro.config.mjs”
This file is generated in every starter template and includes configuration options for your Astro project. Here you can specify integrations to use, build options, server options, and more.
Astro supports several file formats for its JavaScript configuration file: astro.config.js, astro.config.mjs, astro.config.cjs and astro.config.ts. We recommend using .mjs in most cases or .ts if you want to write TypeScript in your config file.
TypeScript config file loading is handled using tsm and will respect your project’s tsconfig options.
See the configuration reference for complete details.
tsconfig.jsonSection titled “tsconfig.json”
This file is generated in every starter template and includes TypeScript configuration options for your Astro project. Some features (like npm package imports) aren’t fully supported in the editor without a tsconfig.json file.
See the TypeScript Guide for details on setting configurations.
How to start working on a new project.
Once you have an Astro project, now you’re ready to build with Astro! 🚀
Section titled “Edit your project”
To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code.
You can also customize aspects of your development environment such as configuring TypeScript or installing the official Astro editor extensions.
Section titled “Start the Astro dev server”
Astro comes with a built-in development server that has everything you need for project development. The astro dev CLI command will start the local development server so that you can see your new website in action for the very first time.
Every starter template comes with a pre-configured script that will run astro dev for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server.
npm
npm run dev
pnpm
pnpm run dev
Yarn
yarn run dev
If all goes well, Astro will now be serving your project on http://localhost:4321/. Visit that link in your browser and see your new site!
Section titled “Work in development mode”
Astro will listen for live file changes in your src/ directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running.
When viewing your site in the browser, you’ll have access to the Astro dev toolbar. As you build, it will help you inspect your islands, spot accessibility issues, and more.
If you aren’t able to open your project in the browser after starting the dev server, go back to the terminal where you ran the dev command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than http://localhost:4321/.
Section titled “Build and preview your site”
To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command for your package manager in your terminal:
npm
npm run build
pnpm
pnpm build
Yarn
yarn run build
Astro will build a deploy-ready version of your site in a separate folder (dist/ by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to strict or strictest, the build script will also check your project for type errors.
When the build is finished, run the appropriate preview command (e.g. npm run preview) in your terminal and you can view the built version of your site locally in the same browser preview window.
Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will not be reflected while you preview your site until you run the build command again.
Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to working in development mode which does update as you edit to show a live preview of your code changes.
Read more about the Astro CLI and the terminal commands you will use as you build with Astro.
Tip
You may wish to deploy your new site right away, before you begin to add or change too much code. This is helpful to get a minimal, working version of your site published and can save you extra time and effort troubleshooting your deployment later.
Success! You are now ready to start building with Astro! 🥳
Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new Astro project codebase, coming back here whenever you run into trouble or have a question.
Section titled “Configure your dev environment”
Explore the guides below to customize your development experience.
Editor Setup Customize your code editor to improve the Astro developer experience and unlock new features.
Dev Toolbar Explore the helpful features of the dev toolbar.
TypeScript Configuration Configure options for type-checking, IntelliSense, and more.
Section titled “Explore Astro’s Features”
Understand your codebase Learn about Astro’s file structure in our Project Structure guide.
Create content collections Add content to your new site with frontmatter validation and automatic type-safety.
Add view transitions Create seamless page transitions and animations.
Learn about Islands Read about Astro's islands architecture.
Section titled “Take the introductory tutorial”
Build a fully functional Astro blog starting from a single blank page in our introductory tutorial.
This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site.
Get to know the ways you can configure and customize your new project and your development experience.
Astro is a flexible, unopinionated framework that allows you to configure your project in many different ways. This means that getting started with a new project might feel overwhelming: there is no “one best way” to set up your Astro project!
The guides in this “Configuration” section will help you familiarize yourself with the various files that allow you to configure and customize aspects of your project and development environment.
If this is your first Astro project, or if it’s been a while since you’ve set up a new project, use the following guides and reference in the documentation for assistance.
Section titled “The Astro config File”
The Astro config file is a JavaScript file included at the root of every starter project:
astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
// your configuration options here...
});
It is only required if you have something to configure, but most projects will use this file. The defineConfig() helper provides automatic IntelliSense in your IDE and is where you will add all your configuration options to tell Astro how to build and render your project to HTML.
We recommend using the default file format .mjs in most cases, or .ts if you want to write TypeScript in your config file. However, astro.config.js and astro.config.cjs are also supported.
Read Astro’s configuration reference for a full overview of all supported configuration options.
Section titled “The TypeScript config File”
Every Astro starter project includes a tsconfig.json file in your project. Astro’s component script is Typescript, which provides Astro’s editor tooling and allows you to optionally add syntax to your JavaScript for type checking of your own project code.
Use the tsconfig.json file to configure the TypeScript template that will perform type checks on your code, configure TypeScript plugins, set import aliases, and more.
Read Astro’s TypeScript guide for a full overview of TypeScript options and Astro’s built-in utility types.
Section titled “Development Experience”
While you work in development mode, you can take advantage of your code editor and other tools to improve the Astro developer experience.
Astro provides its own official VS Code extension and is compatible with several other popular editor tools. Astro also provides a customizable toolbar that displays in your browser preview while the dev server is running. You can install and even build your own toolbar apps for additional functionality.
Read Astro’s guides to editor setup options and using the dev toolbar to learn how to customize your development experience.
Section titled “Common new project tasks”
Here are some first steps you might choose to take with a new Astro project.
Section titled “Add your deployment domain”
For generating your sitemap and creating canonical URLs, configure your deployment URL in the site option. If you are deploying to a path (e.g. www.example.com/docs), you can also configure a base for the root of your project.
Additionally, different deployment hosts may have different behavior regarding trailing slashes at the end of your URLs. (e.g. example.com/about vs example.com/about/). Once your site is deployed, you may need to configure your trailingSlash preference.
astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
site: "https://www.example.com",
base: "/docs",
trailingSlash: "always",
});
Section titled “Add site metadata”
Astro does not use its configuration file for common SEO or meta data, only for information required to build your project code and render it to HTML.
Instead, this information is added to your page <head> using standard HTML <link> and <meta> tags, just as if you were writing plain HTML pages.
One common pattern for Astro sites is to create a <Head /> .astro component that can be added to a common layout component so it can apply to all your pages.
src/components/MainLayout.astro
---
import Head from "./Head.astro";
const { ...props } = Astro.props;
---
<html>
<head>
<meta charset="utf-8">
<Head />
<!-- Additional head elements -->
</head>
<body>
<!-- Page content goes here -->
</body>
</html>
Because Head.astro is just a regular Astro component, you can import files and receive props passed from other components, such as a specific page title.
src/components/Head.astro
---
import Favicon from "../assets/Favicon.astro";
import SomeOtherTags from "./SomeOtherTags.astro";
const { title = "My Astro Website", ...props } = Astro.props;
---
<link rel="sitemap" href="/sitemap-index.xml">
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">
<!-- Web analytics -->
<script data-goatcounter="https://my-account.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>
<!-- Open Graph tags -->
<meta property="og:title" content="My New Astro Website" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://www.example.com/" />
<meta property="og:description" content="Welcome to my new Astro site!" />
<meta property="og:image" content="https://www.example.com/_astro/seo-banner.BZD7kegZ.webp">
<meta property="og:image:alt" content="">
<SomeOtherTags />
<Favicon />
Learn Astro with out-of-this-world courses and tutorials.
Want to get started learning Astro with a course or tutorial?
You can learn the basics of Astro with our official docs Build a Blog tutorial, or explore our collection of recommended Astro educational content.
Section titled “Education Partners”
Support Astro while you learn
Use Astro’s affiliate links for discounts with our education partners and some of your purchase goes directly back to funding development of the Astro open source project!
Learn Astro from trusted Astro educators, with video lessons, interactive challenges, and projects!
Learn Astro with Coding in Public A premium interactive course with 150+ video lessons that teaches you how to use Astro’s built-in tooling and features.
Learn Astro with James Q Quick Build your first Astro site with 35 interactive Scrimba lessons, with video and IDE merged into one unique learning platform.
Section titled “Community learning resources”
Learn from your fellow astronauts with curated collections of guides, articles, and blog posts.
Astro Tips Advanced, unusual, experimental, and community-written recipes, tutorials, and quick tips.
Astro Support Squid An open, public Astro support forum and knowledge base outside of the Astro Discord.
An introduction to Astro components.
Astro components are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime and use the .astro file extension.
Note
If you know HTML, you already know enough to write your first Astro component.
Learn more in the Astro syntax reference.
Astro components are extremely flexible. An Astro component can be as small as a snippet of HTML, like a collection of common <meta> tags that make SEO easy to work with. Components can be reusable UI elements, like a header or a profile card. Astro components can even contain an entire page layout or, when located in the special src/pages/ folder, be an entire page itself.
The most important thing to know about Astro components is that they don’t render on the client. They render to HTML either at build-time or on-demand. You can include JavaScript code inside of your component frontmatter, and all of it will be stripped from the final page sent to your users’ browsers. The result is a faster site, with zero JavaScript footprint added by default.
When your Astro component does need client-side interactivity, you can add standard HTML <script> tags or UI Framework components as “client islands”.
For components that need to render personalized or dynamic content, you can defer their server rendering by adding a server directive. These “server islands” will render their content when it is available, without delaying the entire page load.
Section titled “Component Structure”
An Astro component is made up of two main parts: the Component Script and the Component Template. Each part performs a different job, but together they provide a framework that is both easy to use and expressive enough to handle whatever you might want to build.
src/components/EmptyComponent.astro
---
// Component Script (JavaScript)
---
<!-- Component Template (HTML + JS Expressions) -->
Section titled “The Component Script”
Astro uses a code fence (---) to identify the component script in your Astro component. If you’ve ever written Markdown before, you may already be familiar with a similar concept called frontmatter. Astro’s idea of a component script was directly inspired by this concept.
You can use the component script to write any JavaScript code that you need to render your template. This can include:
src/components/MyComponent.astro
---
import SomeAstroComponent from '../components/SomeAstroComponent.astro';
import SomeReactComponent from '../components/SomeReactComponent.jsx';
import someData from '../data/pokemon.json';
// Access passed-in component props, like `<X title="Hello, World" />`
const { title } = Astro.props;
// Fetch external data, even from a private API or database
const data = await fetch('SOME_SECRET_API_URL/users').then(r => r.json());
---
<!-- Your template here! -->
The code fence is designed to guarantee that the JavaScript that you write in it is “fenced in.” It won’t escape into your frontend application, or fall into your user’s hands. You can safely write code here that is expensive or sensitive (like a call to your private database) without worrying about it ever ending up in your user’s browser.
Note
The Astro component script is TypeScript, which allows you to add additional syntax to JavaScript for editor tooling, and error checking.
Read more about Astro’s built-in TypeScript support.
Section titled “The Component Template”
The component template is below the code fence and determines the HTML output of your component.
If you write plain HTML here, your component will render that HTML in any Astro page it is imported and used.
However, Astro’s component template syntax also supports JavaScript expressions, Astro <style> and <script> tags, imported components, and special Astro directives. Data and values defined in the component script can be used in the component template to produce dynamically-created HTML.
src/components/MyFavoritePokemon.astro
---
// Your component script here!
import Banner from '../components/Banner.astro';
import Avatar from '../components/Avatar.astro';
import ReactPokemonComponent from '../components/ReactPokemonComponent.jsx';
const myFavoritePokemon = [/* ... */];
const { title } = Astro.props;
---
<!-- HTML comments supported! -->
{/* JS comment syntax is also valid! */}
<Banner />
<h1>Hello, world!</h1>
<!-- Use props and other variables from the component script: -->
<p>{title}</p>
<!-- Delay component rendering and provide fallback loading content: -->
<Avatar server:defer>
<svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>
<!-- Include other UI framework components with a `client:` directive to hydrate: -->
<ReactPokemonComponent client:visible />
<!-- Mix HTML with JavaScript expressions, similar to JSX: -->
<ul>
{myFavoritePokemon.map((data) => <li>{data.name}</li>)}
</ul>
<!-- Use a template directive to build class names from multiple strings or even objects! -->
<p class:list={["add", "dynamic", { classNames: true }]} />
Section titled “Component-based design”
Components are designed to be reusable and composable. You can use components inside of other components to build more and more advanced UI. For example, a Button component could be used to create a ButtonGroup component:
src/components/ButtonGroup.astro
---
import Button from './Button.astro';
---
<div>
<Button title="Button 1" />
<Button title="Button 2" />
<Button title="Button 3" />
</div>
Section titled “Component Props”
An Astro component can define and accept props. These props then become available to the component template for rendering HTML. Props are available on the Astro.props global in your frontmatter script.
Here is an example of a component that receives a greeting prop and a name prop. Notice that the props to be received are destructured from the global Astro.props object.
src/components/GreetingHeadline.astro
---
// Usage: <GreetingHeadline greeting="Howdy" name="Partner" />
const { greeting, name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
This component, when imported and rendered in other Astro components, layouts or pages, can pass these props as attributes:
src/components/GreetingCard.astro
---
import GreetingHeadline from './GreetingHeadline.astro';
const name = 'Astro';
---
<h1>Greeting Card</h1>
<GreetingHeadline greeting="Hi" name={name} />
<p>I hope you have a wonderful day!</p>
You can also define your props with TypeScript with a Props type interface. Astro will automatically pick up the Props interface in your frontmatter and give type warnings/errors. These props can also be given default values when destructured from Astro.props.
src/components/GreetingHeadline.astro
---
+interface Props {
+ name: string;
+ greeting?: string;
+}
const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
Component props can be given default values to use when none are provided.
src/components/GreetingHeadline.astro
---
const { greeting = "Hello", name = "Astronaut" } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
The <slot /> element is a placeholder for external HTML content, allowing you to inject (or “slot”) child elements from other files into your component template.
By default, all child elements passed to a component will be rendered in its <slot />.
Note
Unlike props, which are attributes passed to an Astro component available for use throughout your component with Astro.props, slots render child HTML elements where they are written.
src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<Logo />
<h1>{title}</h1>
<slot /> <!-- children will go here -->
<Footer />
</div>
src/pages/fred.astro
---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Fred's Page">
<h2>All about Fred</h2>
<p>Here is some stuff about Fred.</p>
</Wrapper>
This pattern is the basis of an Astro layout component: an entire page of HTML content can be “wrapped” with <SomeLayoutComponent></SomeLayoutComponent> tags and sent to the component to render inside of common page elements defined there.
See the Astro.slots utility functions for more ways to access and render slot content.
An Astro component can also have named slots. This allows you to pass only HTML elements with the corresponding slot name into a slot’s location.
Slots are named using the name attribute:
src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<!-- children with the `slot="after-header"` attribute will go here -->
<slot name="after-header" />
<Logo />
<h1>{title}</h1>
<!-- children without a `slot`, or with `slot="default"` attribute will go here -->
<slot />
<Footer />
<!-- children with the `slot="after-footer"` attribute will go here -->
<slot name="after-footer" />
</div>
To inject HTML content into a particular slot, use the slot attribute on any child element to specify the name of the slot. All other child elements of the component will be injected into the default (unnamed) <slot />.
src/pages/fred.astro
---
import Wrapper from '../components/Wrapper.astro';
---
<Wrapper title="Fred's Page">
<img src="https://my.photo/fred.jpg" slot="after-header" />
<h2>All about Fred</h2>
<p>Here is some stuff about Fred.</p>
<p slot="after-footer">Copyright 2022</p>
</Wrapper>
Tip
Use a slot="my-slot" attribute on the child element that you want to pass through to a matching <slot name="my-slot" /> placeholder in your component.
To pass multiple HTML elements into a component’s <slot/> placeholder without a wrapping <div>, use the slot="" attribute on Astro’s <Fragment/> component:
src/components/CustomTable.astro
---
// Create a custom table with named slot placeholders for header and body content
---
<table class="bg-white">
<thead class="sticky top-0 bg-white"><slot name="header" /></thead>
<tbody class="[&_tr:nth-child(odd)]:bg-gray-100"><slot name="body" /></tbody>
</table>
Inject multiple rows and columns of HTML content using a slot="" attribute to specify the "header" and "body" content. Individual HTML elements can also be styled:
src/components/StockTable.astro
---
import CustomTable from './CustomTable.astro';
---
<CustomTable>
<Fragment slot="header"> <!-- pass table header -->
<tr><th>Product name</th><th>Stock units</th></tr>
</Fragment>
<Fragment slot="body"> <!-- pass table body -->
<tr><td>Flip-flops</td><td>64</td></tr>
<tr><td>Boots</td><td>32</td></tr>
<tr><td>Sneakers</td><td class="text-red-500">0</td></tr>
</Fragment>
</CustomTable>
Note that named slots must be an immediate child of the component. You cannot pass named slots through nested elements.
Tip
Named slots can also be passed to UI framework components!
Note
It is not possible to dynamically generate an Astro slot name, such as within a map function. If this feature is needed within UI framework components, it might be best to generate these dynamic slots within the framework itself.
Section titled “Fallback Content for Slots”
Slots can also render fallback content. When there are no matching children passed to a slot, a <slot /> element will render its own placeholder children.
src/components/Wrapper.astro
---
import Header from './Header.astro';
import Logo from './Logo.astro';
import Footer from './Footer.astro';
const { title } = Astro.props;
---
<div id="content-wrapper">
<Header />
<Logo />
<h1>{title}</h1>
<slot>
<p>This is my fallback content, if there is no child passed into slot</p>
</slot>
<Footer />
</div>
Fallback content will only be displayed when there are no matching elements with the slot="name" attribute being passed in to a named slot.
Astro will pass an empty slot when a slot element exists but has no content to pass. Fallback content cannot be used as a default when an empty slot is passed. Fallback content is only displayed when no slot element can be found.
Section titled “Transferring slots”
Slots can be transferred to other components. For example, when creating nested layouts:
src/layouts/BaseLayout.astro
---
---
<html lang="en">
<head>
<meta charset="utf-8" />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="viewport" content="width=device-width" />
<meta name="generator" content={Astro.generator} />
<slot name="head" />
</head>
<body>
<slot />
</body>
</html>
src/layouts/HomeLayout.astro
---
import BaseLayout from './BaseLayout.astro';
---
<BaseLayout>
<slot name="head" slot="head" />
<slot />
</BaseLayout>
Note
Named slots can be transferred to another component using both the name and slot attributes on a <slot /> tag.
Now, the default and head slots passed to HomeLayout will be transferred to the BaseLayout parent.
src/pages/index.astro
---
import HomeLayout from '../layouts/HomeLayout.astro';
---
<HomeLayout>
<title slot="head">Astro</title>
<h1>Astro</h1>
</HomeLayout>
Section titled “HTML Components”
Astro supports importing and using .html files as components or placing these files within the src/pages/ subdirectory as pages. You may want to use HTML components if you’re reusing code from an existing site built without a framework, or if you want to ensure that your component has no dynamic features.
HTML components must contain only valid HTML, and therefore lack key Astro component features:
<script> tags are left unbundled, treated as if they had an is:inline directive.public/ folder.Note
A <slot /> element inside an HTML component will work as it would in an Astro component. In order to use the HTML Web Component Slot element instead, add is:inline to your <slot> element.
Read more about using UI framework components in your Astro project.
An introduction to Astro pages.
Pages are files that live in the src/pages/ subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website.
Section titled “Supported page files”
Astro supports the following file types in the src/pages/ directory:
.astro.md.mdx (with the MDX Integration installed).html.js/.ts (as endpoints)Section titled “File-based routing”
Astro leverages a routing strategy called file-based routing. Each file in your src/pages/ directory becomes an endpoint on your site based on its file path.
A single file can also generate multiple pages using dynamic routing. This allows you to create pages even if your content lives outside of the special /pages/ directory, such as in a content collection or a CMS.
Read more about Routing in Astro.
Section titled “Link between pages”
Write standard HTML <a> elements in your Astro pages to link to other pages on your site. Use a URL path relative to your root domain as your link, not a relative file path.
For example, to link to https://example.com/authors/sonali/ from any other page on example.com:
src/pages/index.astro
Read more <a href="/authors/sonali/">about Sonali</a>.
Astro pages use the .astro file extension and support the same features as Astro components.
src/pages/index.astro
---
---
<html lang="en">
<head>
<title>My Homepage</title>
</head>
<body>
<h1>Welcome to my website!</h1>
</body>
</html>
A page must produce a full HTML document. If not explicitly included, Astro will add the necessary <!DOCTYPE html> declaration and <head> content to any .astro component located within src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.
To avoid repeating the same HTML elements on every page, you can move common <head> and <body> elements into your own layout components. You can use as many or as few layout components as you’d like.
src/pages/index.astro
---
import MySiteLayout from "../layouts/MySiteLayout.astro";
---
<MySiteLayout>
<p>My page content, wrapped in a layout!</p>
</MySiteLayout>
Read more about layout components in Astro.
Section titled “Markdown/MDX Pages”
Astro also treats any Markdown (.md) files inside of src/pages/ as pages in your final website. If you have the MDX Integration installed, it also treats MDX (.mdx) files the same way.
Tip
Consider creating content collections instead of pages for directories of related Markdown files that share a similar structure, such as blog posts or product items.
Markdown files can use the special layout frontmatter property to specify a layout component that will wrap their Markdown content in a full <html>...</html> page document.
src/pages/page.md
---
layout: ../layouts/MySiteLayout.astro
title: My Markdown page
---
# Title
This is my page, written in **Markdown.**
Read more about Markdown in Astro.
Files with the .html file extension can be placed in the src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components.
Section titled “Custom 404 Error Page”
For a custom 404 error page, you can create a 404.astro or 404.md file in src/pages.
This will build to a 404.html page. Most deploy services will find and use it.
Section titled “Custom 500 Error Page”
For a custom 500 error page to show for pages that are rendered on demand, create the file src/pages/500.astro. This custom page is not available for prerendered pages.
If an error occurs rendering this page, your host’s default 500 error page will be shown to your visitor.
Added in: astro@4.10.3
During development, if you have a 500.astro, the error thrown at runtime is logged in your terminal, as opposed to being shown in the error overlay.
errorAdded in: astro@4.11.0
src/pages/500.astro is a special page that is automatically passed an error prop for any error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor.
The error prop’s data type can be anything, which may affect how you type or use the value in your code:
src/pages/500.astro
---
interface Props {
error: unknown;
}
const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "Unknown error"}</div>
To avoid leaking sensitive information when displaying content from the error prop, consider evaluating the error first, and returning appropriate content based on the error thrown. For example, you should avoid displaying the error’s stack as it contains information about how your code is structured on the server.
Section titled “Page Partials”
Added in: astro@3.4.0
Caution
Page partials are intended to be used in conjunction with a front-end library, such as htmx or Unpoly. You can also use them if you are comfortable writing low-level front-end JavaScript. For this reason they are an advanced feature.
Additionally, partials should not be used if the component contains scoped styles or scripts, as these elements will be stripped from the HTML output. If you need scoped styles, it is better to use regular, non-partial pages along with a frontend library that knows how to merge the contents into the head.
Partials are page components located within src/pages/ that are not intended to render as full pages.
Like components located outside of this folder, these files do not automatically include the <!DOCTYPE html> declaration, nor any <head> content such as scoped styles and scripts.
However, because they are located in the special src/pages/ directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. htmx, Stimulus, jQuery) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation.
Partials, when combined with a rendering library, provide an alternative to Astro islands and <script> tags for building dynamic content in Astro.
Page files that can export a value for partial (e.g. .astro and .mdx, but not .md) can be marked as partials.
src/pages/partial.astro
---
+export const partial = true;
---
<li>I'm a partial!</li>
Section titled “Using with a library”
Partials are used to dynamically update a section of a page using a library such as htmx.
The following example shows an hx-post attribute set to a partial’s URL. The content from the partial page will be used to update the targeted HTML element on this page.
src/pages/index.astro
<html>
<head>
<title>My page</title>
<script src="https://unpkg.com/htmx.org@1.9.6"
integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
crossorigin="anonymous"></script>
</head>
<body>
<section>
<div id="parent-div">Target here</div>
<button hx-post="/partials/clicked/"
hx-trigger="click"
hx-target="#parent-div"
hx-swap="innerHTML"
>
Click Me!
</button>
</section>
</body>
</html>
The .astro partial must exist at the corresponding file path, and include an export defining the page as a partial:
src/pages/partials/clicked.astro
---
export const partial = true;
---
<div>I was clicked!</div>
See the htmx documentation for more details on using htmx.
An introduction to layouts in Astro.
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:
<html>, <head> and <body> tags)<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.
However, if a layout component does contain a page shell, its <html> element must be the parent of all other elements in the component.
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 _.
Section titled “Sample Layout”
src/layouts/MySiteLayout.astro
---
import BaseHead from '../components/BaseHead.astro';
import Footer from '../components/Footer.astro';
const { title } = Astro.props;
---
<html lang="en">
<head>
Auto-correct relative links, asset paths, and related links in markdown documents based on folder depth.
Import YouTube video details using yt-dlp, automatically generating Astro Markdown pages with metadata, iframe embeds, and descriptions.
Ensure all markdown documents have their frontmatter titles injected as standard H1 headings at the start of the body.
Scrape, download, and localize external or relative images referenced in markdown files to Astro's src/assets folder and rewrite image links.
Process all markdown documentation files to generate AI summaries and embeddings (using Ollama), apply taxonomy tags, and compute KNN related links.