How to Supercharge Your Astro Site with a Custom Markdown Component

Introduction

Working with Markdown inside Astro components can save you time and reduce clutter. Instead of wrapping each line in <p>, <strong>, or <em>, you can use a dedicated Markdown component that does the heavy lifting for you. This guide will show you how to install, configure, and use a Markdown component in your Astro project, so you can focus on writing clean content while still getting proper HTML output. We’ll also cover the inline option and how to keep Prettier from messing up your syntax.

What You Need

• An existing Astro project (version 3 or higher recommended)
• Node.js (v16 or later)
• Basic familiarity with Astro components and Markdown syntax
• A package manager: npm, yarn, pnpm, or bun

Step-by-Step Instructions

Step 1: Understand What a Markdown Component Does

In Astro, you normally write HTML or JSX to render content. A Markdown component lets you drop raw Markdown inside your component template and have it automatically transformed into proper HTML. This means you can write headings, paragraphs, lists, links, and inline formatting without manually typing opening and closing tags. The component also converts typographic symbols (like straight apostrophes or quotes) into their curly equivalents automatically.

Originally, Astro had a built-in <Markdown> component, but it was moved to an external package in version 1 and removed entirely in version 3. The community-maintained @splendidlabz/astro package provides a drop-in replacement.

Step 2: Install the Markdown Component Package

Open your terminal, navigate to your Astro project root, and install the package using your preferred package manager:

npm install @splendidlabz/astro

or

yarn add @splendidlabz/astro

Once installed, the <Markdown> component will be available for import.

Step 3: Import and Use the Component

In any Astro component (.astro file), add the import at the top of the frontmatter:

---
import { Markdown } from '@splendidlabz/astro';
---

Then use it anywhere in your template. Surround your Markdown content with the opening and closing tags:

<div class="card">
  <Markdown>
    ## Card Title
    This is a paragraph with **strong** and *italic* text.
    Here's a [link](https://example.com).

    - Item 1
    - Item 2
  </Markdown>
</div>

The component will output standard HTML tags, making your content semantic and accessible without extra markup.

Step 4: Take Advantage of Automatic Indentation Handling

One of the best features is that the component respects the indentation of your Markdown. You can nest it inside deeply indented structures without worrying about unwanted <pre> or <code> tags. For example:

<section>
  <article>
    <Markdown>
      This is the first paragraph.

      This is the second paragraph.
    </Markdown>
  </article>
</section>

The output will be clean, with each paragraph wrapped in <p> tags and no unwanted extra indentation.

Step 5: Use the Inline Option for Short Snippets

Sometimes you only need to apply Markdown inline formatting — like bold or italic — inside a heading or a single element. Use the inline prop to suppress the automatic paragraph wrapping:

<h2 class="max-w-2xl">
  <Markdown inline> Ain't this cool? </Markdown>
</h2>

This outputs:

<h2 class="max-w-2xl">
  Ain't this cool?
</h2>

Notice that the apostrophe was converted to a curly right single quote automatically.

Step 6: Prevent Prettier from Ruining Your Markdown

Prettier, a popular code formatter, may try to reformat the contents inside the <Markdown> block, which can break intentional spacing or indentation. To avoid this, add an HTML comment <!-- prettier-ignore --> just before the opening <Markdown> tag:

<div>
  <!-- prettier-ignore -->
  <Markdown>
    This will stay exactly as I wrote it.

    - Not
    - Reformatted
  </Markdown>
</div>

This tells Prettier to skip formatting that block, preserving your Markdown structure.

Tips & Best Practices

• Keep it simple: Use the Markdown component for content-heavy sections like blog posts, cards, or documentation blocks. For simple text, plain HTML is often faster.
• Combine with Typography: The component automatically handles smart quotes and dashes — no extra plugins needed.
• Be careful with headings: If you need to add classes to headings, you can still use <h2 class="..."> outside the component, but you’ll lose the Markdown shorthand. For readability, it’s fine to keep headings inside the component and style them globally.
• Always use <!-- prettier-ignore --> if your project uses Prettier, especially when the Markdown block is deeply nested.
• Check your version: The @splendidlabz/astro package works with Astro 3+. If you’re on an older version, consider upgrading or using a different approach.
• Don’t over-nest: While the component handles indentation, deeply nested Markdown inside multiple divs can be harder to read. Keep your structure shallow when possible.