Use Markdown Files for Astro Content Collections

Learn to Organize Your Website Content with Markdown Files in Astro

In this guide, you’ll learn how to switch your Astro content collections from using a single JSON file to using individual Markdown files. This makes managing content like book reviews much easier. We’ll cover updating your collection configuration and linking to your new Markdown content. By the end, your website will be better organized and easier to update.

Prerequisites

• Basic understanding of Astro and its content collections.
• Familiarity with JSON and Markdown file formats.
• Access to your Astro project files.

Step 1: Understand Why Markdown is Better for Content

Imagine you’re building a website to review books. Using a single JSON file for all reviews can become messy quickly. Each book has its own title, author, summary, and rating. Plus, each review will have a lot of detailed content like headings, lists, and quotes. Markdown files are perfect for this. They let you structure each review’s content naturally, just like writing a document. Astro makes it easy to use these files for your content collections.

Step 2: Create a New Folder for Your Markdown Files

First, create a new folder inside your project’s content folder. Name this folder something descriptive, like books. This keeps your content organized. If you plan to add other types of content later, like blog posts, you can create separate folders for them too. This prevents everything from getting mixed up.

Inside the new books folder, create individual Markdown (.md) files for each item. For example, if you’re reviewing a book called “Assassin’s Apprentice,” create a file named assassin-apprentice.md. The filename will automatically become the item’s unique ID in Astro.

Step 3: Add Front Matter to Your Markdown Files

Open one of your new Markdown files. At the very top, you’ll add something called “front matter.” This is like a header for your file, where you define metadata. Use a simple format with three dashes (---) on lines before and after your metadata.

Inside the front matter, list the properties for your content. For our book example, this includes title, author, summary, and rating. These are the same properties you might have had in your old JSON file. You don’t need to add an id here because Astro uses the filename as the ID.

Here’s an example of front matter:

---
title: "Assassin's Apprentice"
author: "Robin Hobb"
summary: "A tale of political intrigue and a young boy's destiny."
rating: 5
---

Step 4: Add Content Below the Front Matter

After the closing --- of your front matter, you can write the main content for your item. Use standard Markdown formatting here. You can add headings (like # Chapter 1), lists (using hyphens or asterisks), quotes, and paragraphs. This is where the detailed information for each book review will go.

Astro will automatically process this Markdown content. You don’t need special code to tell it how to handle headings or lists. It’s designed to work seamlessly with Markdown.

Step 5: Update Your Content Collection Configuration

Now, you need to tell Astro to use these new Markdown files. Open your src/content.config.ts file. This is where you define your content collections.

You’ll make two main changes here:

Change the Loader

The current loader likely uses a function called file, which is for single files. Since you now have many Markdown files, you need to use a function called glob. This function helps Astro find multiple files that match a pattern.

First, import glob from astro/loaders. You can then remove the import for file. Replace the old loader with the glob function. The glob function needs to know where to look and what files to find.

Provide an object to the glob function with two properties:

• base: This is the starting folder. For our example, it’s src/content/books.
• pattern: This tells Astro which files to include. Use *.md to find all files ending with .md in the specified base folder.

Your updated loader configuration might look like this:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const booksCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    author: z.string(),
    summary: z.string(),
    rating: z.number().min(1).max(5),
  }),
  // New loader configuration using glob
  // Make sure the base path matches your project structure
  loaders: { 
    books: glob(
      { 
        base: 'src/content/books', 
        pattern: '*.md'
      }
    )
  }
});

export default { 
  collections: {
    books: booksCollection
  }
};

Update the Schema

Because Astro automatically uses the filename as the ID, you no longer need to define an id in your schema. Remove the id property from the z.object({...}) part of your schema. The schema should now only include properties defined in your front matter (title, author, summary, rating).

You don’t need to add anything to the schema for the actual Markdown content itself. Astro handles that separately.

Step 6: Link to Your Content Using Auto-Generated IDs

Now, let’s make sure your links work correctly. Open the component where you display your book items, often called a “book card” component. You’ll find an anchor tag (<a>) that’s meant for a “Read More” link.

You need to make this link dynamic so it points to the correct page for each book. You’ll use the ID that Astro generated from the filename.

Update the href attribute of the anchor tag. Use template strings (backticks “ ` “) and embed the ID using ${book.id}. The path should start with /books/, followed by the book’s ID.

Your updated anchor tag might look like this:

<a href={`/books/${book.id}`}>Read More</a>

Expert Note: When you access the ID, remember that it’s part of the entry object itself, not directly attached to the data object you defined in the schema. So, if your data object is named book, you’ll use book.id.

Step 7: Preview Your Changes

Save all your changes. Run your Astro development server again using the command npm run dev or yarn dev. Visit your website in the browser.

You should see your book items displayed as before. The “Read More” links should now be active. When you click on a link, for example, for “Assassin’s Apprentice,” the URL should change to something like /books/assassin-apprentice. This shows that Astro is correctly using the filenames as IDs for your links.

Currently, you might see a 404 error page when you click a link. This is normal because you haven’t created the actual pages for each book’s detail view yet. The important part is that the links are now pointing to the correct, unique URLs for each book, using their filenames as IDs.

Source: Astro Crash Course #9 – Content Collections (with Markdown) (YouTube)