Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Content Collections and Markdown

Markdown Pages and Frontmatter

Write pages in Markdown with Astro: frontmatter, the layout field, GitHub-flavored extras, heading IDs, syntax highlighting with Shiki and MDX components.

Writing long articles in HTML is tedious. Markdown lets authors focus on words: # for headings, * for emphasis, a backtick for code. Astro supports Markdown out of the box, so a .md file in src/pages/ is a page, and this is the quickest way to publish text content.

In this lesson you will write Markdown pages, add structured data with frontmatter, connect a layout, and learn which Markdown features Astro provides. The next lessons show a more scalable approach, content collections, for sites with many posts.

A Markdown page

Create src/pages/posts/hello.md:

MARKDOWN
---
title: "Hello, Astro"
pubDate: 2026-02-10
author: "Mina"
tags: ["astro", "intro"]
layout: ../../layouts/PostLayout.astro
---

# Hello, Astro

This is my **first** post. Here is a list:

- Markdown is quick
- Frontmatter holds data

## A code sample

```js
console.log("Hello from a Markdown page");
```

The page is served at /posts/hello. The block between the two --- lines at the top is frontmatter, written in YAML. It stores metadata about the page: title, date, tags and anything else you need.

Connecting a layout

The layout field names an Astro component that wraps the rendered Markdown. The layout receives the frontmatter as Astro.props.frontmatter and the converted HTML in the default slot:

ASTRO
---
// src/layouts/PostLayout.astro
import BaseLayout from "./BaseLayout.astro";
const { frontmatter } = Astro.props;
---
<BaseLayout title={frontmatter.title}>
  <article>
    <h1>{frontmatter.title}</h1>
    <p>By {frontmatter.author} on {frontmatter.pubDate.toString().slice(0, 10)}</p>
    <slot />
  </article>
</BaseLayout>

Since the Markdown body usually starts with its own heading, many authors leave the # heading out of the file and let the layout print the title from frontmatter. Pick one place for the h1 and keep it consistent.

Markdown page parts

Frontmatter YAML data between dashes
Body Markdown text
1 / 2

What Markdown features are available

Astro uses a Markdown pipeline built on remark and rehype, with sensible defaults:

  • GitHub-flavored Markdown (GFM): tables, task lists, strikethrough and automatic links.
  • SmartyPants: straight quotes become curly quotes and -- becomes a dash.
  • Heading IDs: every heading gets an id so you can link to #a-code-sample.
  • Syntax highlighting: code fences are colored at build time by Shiki, with no client JavaScript. Choose a theme in the config.
JavaScript
// astro.config.mjs
export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: "github-dark",
      wrap: true,
    },
    gfm: true,
    smartypants: true,
  },
});

Tables work with the standard syntax:

MARKDOWN
| Plan  | Price |
| ----- | ----- |
| Free  | $0    |
| Pro   | $12   |

Using frontmatter elsewhere

Other pages can read the frontmatter of Markdown files with import.meta.glob, which loads many modules at once:

ASTRO
---
const posts = Object.values(
  import.meta.glob("./posts/*.md", { eager: true })
);
const sorted = posts.sort(
  (a, b) => +new Date(b.frontmatter.pubDate) - +new Date(a.frontmatter.pubDate)
);
---
<ul>
  {sorted.map((post) => (
    <li><a href={post.url}>{post.frontmatter.title}</a></li>
  ))}
</ul>

Each module exposes frontmatter, url, file, rawContent(), compiledContent(), getHeadings() and a Content component. This works for a few pages, but it offers no validation: a typo in a field name becomes a silent undefined. Content collections solve that.

MDX: Markdown with components

Add the MDX integration (npx astro add mdx) and use .mdx files to import and use components inside prose:

MDX
---
title: "Interactive post"
---
import Chart from "../../components/Chart.astro";

# Interactive post

Here is a chart inside the article:

<Chart data={[3, 5, 8]} />

Text continues after the component.

MDX is powerful, but it moves content toward code, so use it where you really need components and keep plain Markdown elsewhere.

Stand-in: frontmatter and Markdown to HTML

Parsing frontmatter and converting a few Markdown forms is a good way to understand what the pipeline does. This stand-in handles a flat YAML subset, headings with ids, bold text, links and lists.

Node.js Stand-in: a tiny Markdown pipeline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Stand-in: building a post index

import.meta.glob plus sorting is the pattern behind most blog index pages. This stand-in sorts frontmatter records by date, filters drafts and formats each entry as a link, the same steps as the Astro example above.

Node.js Stand-in: sorted post index

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Tips for good Markdown content

  • Write one h1 per page, then ## and ###; do not skip levels.
  • Give every image alt text: ![A sunset over hills](./sunset.jpg).
  • Keep frontmatter field names consistent across files, since pages and layouts rely on them.
  • Quote YAML strings that contain a colon, such as title: "Astro: a guide".
  • Use relative image paths (processed and optimized) or /public paths (copied as is).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is frontmatter?

    Frontmatter stores metadata such as title and date. Astro passes it to the layout.
  2. 2. How does a layout read the Markdown page's data?

    Markdown pages pass their frontmatter to the layout through Astro.props.frontmatter.
  3. 3. What colors code blocks in Markdown by default?

    Shiki highlights fences during the build, so no JavaScript is shipped for it.
  4. 4. Which is a weakness of using import.meta.glob for posts?

    Collections add schemas so mistakes are caught at build time.

Summary

  • A .md file in src/pages/ becomes a page; frontmatter holds its metadata.
  • The layout field wraps the output and delivers frontmatter through props.
  • Astro provides GFM, SmartyPants, heading IDs and Shiki highlighting by default.
  • import.meta.glob reads many Markdown pages, but without validation.
  • MDX adds components to Markdown when you need them.

Next: Content Collections and Loaders