Pages and routing
Create a page from Markdown
Use Markdown for content that maps directly to a route and choose content collections when many entries share one content model.
Not every page needs a component. For a page that is mostly text, Markdown is faster to write and easier to read. Astro lets you drop a .md file under src/pages/ and it becomes a route, like any other page.
Here is src/pages/install.md:
---
title: Installation
description: Install the project locally.
---
# Installation
Run the project wizard, then start the development server.Open /install/ in the dev server and you get the rendered content.
What happens to the frontmatter
At build time Astro converts the Markdown body into HTML. The frontmatter values, title and description here, are available to the page and to its layout. They are not sent to the browser as a JavaScript object. They just inform the render.
A Markdown page can point at a layout with a layout key in the frontmatter. The layout receives the frontmatter values and wraps the content in the document shell, with the <head>, the navigation, and so on. We’ll build a layout in the components module.
When Markdown pages fit
They’re perfect for a handful of standalone documents whose file path is their URL. An about page, a privacy policy, an install guide.
They stop fitting when you have many entries of the same kind. Twenty blog posts as Markdown pages means twenty files with nothing checking that each one has a title and a date. Nothing to query them from. No easy way to build a list page.
For that, use a content collection. Collections give a group of Markdown files a schema, a query API, and a clean way to generate routes from entries. We’ll get there in the data module. The rule of thumb: one document, Markdown page. Many similar documents, collection.
Markdown is still HTML
Markdown doesn’t free you from writing good HTML. It just writes it for you. One # heading per page, so the document has one h1. Link text that says where the link goes, not “click here”. Image alt text that describes the image. A layout that adds the <title> and the meta description.
Try this on your project: create the Markdown page above, build, and open dist/install/index.html. Find the h1 and the paragraph. Then remove title from the frontmatter and build again. Does anything complain? With a plain Markdown page, usually not. That silence is one reason collections exist.
Lesson completed