Adding Guides to Your Astro Blog

Intermediate
Category: Site Features

Prerequisites

  • Existing Astro Blog
  • Basic TypeScript
  • Basic Astro Knowledge

Adding Guides to Your Astro Blog

Running a technical blog often means creating content that’s evergreen, structured, and easily referenced, which blog posts alone can’t always provide. Guides serve as a dedicated section for this type of content. In this guide, we’ll walk through how to set up a guide system for your Astro blog, including adding features like categories, difficulty levels, and prerequisites.

Why Create a Separate Guide Section?

Blog posts are great for timely updates, tutorials, and reflections, but guides are better suited for content that’s meant to be referenced over time. Here’s why you might want a dedicated guide section:

Step 1: Define the Guide Collection

First, you need to define a collection specifically for guides in your src/content/config.ts. This defines the schema for your guides and allows for features like difficulty, categories, and more. Here’s what the schema looks like:

const guides = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string(),
    difficulty: z.enum(["beginner", "intermediate", "advanced"]),
    category: z.string(),
    order: z.number().optional(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    prerequisites: z.array(z.string()).optional(),
  }),
});

export const collections = { blog, guides };

Explanation:

Why We Made These Changes:

Step 2: Create a Directory for Guides

To keep your project organized, create a new folder for storing your guide files:

mkdir src/content/guides

Each guide will reside in its own Markdown file within this directory, similar to how you store blog posts, but under its own dedicated folder.

Step 3: Build the Guides Index Page

To display all your guides, create an index page at src/pages/guides/index.astro. This page will:

Example Code for Index Page:

---
import { getCollection } from 'astro:content';
const guides = await getCollection('guides');
---

<h1>Guides</h1>
{guides
  .filter(guide => guide.category)
  .reduce((categories, guide) => {
    (categories[guide.category] ||= []).push(guide);
    return categories;
  }, {}) |> Object.entries
  |> sortCategoriesByOrder
}.map(([category, guides]) => (
  <>
    <h2>{category}</h2>
    <div class="guide-grid">
      {guides.map(guide => (
        <div class="guide-card">
          <img src={guide.heroImage} alt="" />
          <h3>{guide.title}</h3>
          <p>{guide.description}</p>
          <div class="badge {guide.difficulty.toLowerCase()}">{guide.difficulty}</div>
          {guide.prerequisites.length ? (
            <ul>
              {guide.prerequisites.map(pre => (
                <li>{pre}</li>
              ))}
            </ul>
          ) : null}
        </div>
      ))}
    </div>
  </>
))

Features:

Step 4: Custom Styling for Guides

You’ll want your guides to have a unique visual identity compared to your blog posts. Here are some ideas for custom styles:

Example CSS:

.guide-card {
  border: 1px solid #ddd;
  padding: 20px;
  border-radius: 8px;
  transition: transform 0.2s;
}

.guide-card:hover {
  transform: translateY(-5px);
}

.badge {
  padding: 5px 10px;
  border-radius: 5px;
  font-weight: bold;
}

.badge.beginner { background-color: #28a745; }
.badge.intermediate { background-color: #ff9800; }
.badge.advanced { background-color: #e91e63; }

.guide-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 20px;
}

Step 5: Write Your First Guide

When creating a new guide, you’ll define frontmatter just like a blog post. Here’s an example:

---
title: "Adding Guides to Your Astro Blog"
description: "Learn how to extend your Astro blog with a dedicated guides section"
difficulty: "intermediate"
category: "Site Features"
order: 1
prerequisites:
  ["Existing Astro Blog", "Basic TypeScript", "Basic Astro Knowledge"]
---

Write the guide content in Markdown, making sure to:

Best Practices for Writing Guides

Creating well-structured and engaging guides is key to offering a positive learning experience. By following these best practices, you can ensure that your guides provide value to both beginners and experts alike.

1. Select the Right Difficulty Level

Choosing the appropriate difficulty level is essential in setting the right expectations for your readers. Make sure each guide has a clearly defined difficulty level that matches the knowledge and experience required.

2. List Prerequisites Clearly

Clearly state what your readers should know before starting the guide. This not only helps set expectations but also ensures that your readers can follow along without feeling lost.

3. Use Consistent and Relevant Categories

Organizing your guides into consistent, relevant categories makes it easier for users to find the content they need. The categories should be broad enough to cover related topics while still being specific enough to allow for precise classification.

4. Order Your Guides Thoughtfully

The order field allows you to control how guides are presented, especially when creating learning paths or series. Guides should follow a logical progression, building knowledge step-by-step.

5. Use Clear and Descriptive Titles

A guide’s title should give readers an immediate understanding of the topic and difficulty level. Descriptive titles help set expectations and improve searchability.

6. Break Down Content with Headers and Lists

Breaking down complex ideas into digestible sections is key to maintaining readability and engagement.

7. Include Visual Aids

Adding screenshots, diagrams, and videos can dramatically improve comprehension, especially for complex topics.

8. Provide Code Examples

Ensure that you include well-structured code examples to support your explanations. Readers should be able to copy-paste the examples into their own projects to see results.

9. Test Your Guides

Before publishing a guide, thoroughly test each step to ensure that the instructions are correct and work as expected.

10. Keep Guides Evergreen

Since guides are meant to be more permanent than blog posts, periodically update them to reflect changes in technology, frameworks, or tools.

Next Steps: Feature Enhancements

Once you have your guides section set up, consider adding these advanced features to improve the user experience:

Conclusion

Guides offer a more structured, evergreen way of presenting content. With the setup above, you can create categories, define difficulty levels, and offer prerequisites to help users navigate your content more easily. Remember to update your guides as your blog evolves—guides are living documents that can grow and adapt over time.