Transforming Your Astro Workflow: A How-To for the Markdown Component

Introduction

If you're building a site with Astro and find yourself writing repetitive HTML tags for basic content—like paragraphs, lists, and typographic symbols—the Markdown component is a game-changer. This guide takes you through every step to install, configure, and use this component effectively, so you can write cleaner Markdown inside your Astro templates while still getting beautiful HTML output. By the end, you'll be able to reduce markup bloat, automatically convert typographic symbols, and even keep your formatting pristine—all with a simple <Markdown> wrapper.

What You Need

• An existing Astro project (version 3 or later recommended)
• Node.js (v16 or higher) and npm installed
• Basic familiarity with Astro components and syntax
• A code editor (like VS Code) with Prettier installed (optional, but helpful)

Step-by-Step Guide

Step 1: Install the Markdown Component Package

The official @splendidlabz/astro package contains the <Markdown> component. Open your terminal in the project root and run:

npm install @splendidlabz/astro

This adds the component to your dependencies. Once installed, you're ready to import and use it in any Astro component.

Step 2: Import the Component

In any .astro file where you want to use Markdown, add an import statement at the top. The component is exported as a named export from the package.

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

Now you can use <Markdown> just like any other Astro component inside your template.

Step 3: Write Markdown Inside the Component

Wrap your Markdown content with opening and closing <Markdown> tags. Inside, you can use standard Markdown syntax: headings, paragraphs, lists, links, bold, italic, and more. Here's a basic example:

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

    - List
    - Of
    - Items
  </Markdown>
</div>

Important: The <!-- prettier-ignore --> comment tells Prettier not to reformat the contents inside the <Markdown> block, preserving your Markdown indentation and structure.

The component will convert this into proper HTML tags automatically, as shown in the output:

<div class="card">
  <h2> Card Title </h2>
  <p>This is a paragraph with <strong>strong</strong> and <em>italic</em> text.</p>
  <p>This is a second paragraph with <a href="https://example.com">link</a></p>
  <ul>
    <li> List </li>
    <li> Of </li>
    <li> Items </li>
  </ul>
</div>

Step 4: Understand Automatic Indentation Handling

One standout feature of this component is that it respects your indentation without wrapping everything in <pre> and <code> tags. You can nest the Markdown component inside deeply indented structures, and it will output correctly. Example:

<div>
  <div>
    <!-- prettier-ignore -->
    <Markdown>
      This is a paragraph

      This is a second paragraph
    </Markdown>
  </div>
</div>

Output:

<div>
  <div>
    <p>This is a paragraph</p>
    <p>This is a second paragraph</p>
  </div>
</div>

Notice no extra indentation or code block is added—just clean HTML paragraphs.

Step 5: Use the Inline Option for Headings or Text

Sometimes you want to use Markdown inside an inline element (like a heading) without generating paragraph tags. The component offers an inline prop for exactly that. Set it to true to suppress automatic <p> wrapping:

<h2 class="max-w-[12em]">
  <Markdown inline> Ain't this cool? </Markdown>
</h2>

Output:

<h2 class="max-w-[12em]">
  Ain't this cool?
</h2>

This is particularly useful when you want typographic conversions (like smart quotes) inside a heading or any other HTML element.

Step 6: Handle Prettier Formatting Conflicts

The biggest gotcha is that Prettier may reformat your Markdown content inside the <Markdown> block, breaking indentation or adding unwanted spacing. To avoid this, always include <!-- prettier-ignore --> directly before your <Markdown> opening tag. If you forget, the component may still work, but your source code could become messy. Make it a habit to add that comment every time you use the component.

Tips for Best Results

• Prettier-ignore every time: Always place <!-- prettier-ignore --> before <Markdown> to keep your Markdown tidy. If you have multiple blocks, comment each one.
• Use inline for heading content: When you need smart quotes or other typographic conversions inside a heading, wrap the text with <Markdown inline>...</Markdown>.
• Keep your Markdown clean: The component is designed for simple inline markup—avoid complex tables or code blocks inside it; use standard Astro components for those.
• Check the package repository: If you encounter issues, the package source and documentation are available at the SplendidLabz GitHub repo.
• Migrate from older Astro versions: If you used the built-in Markdown component in Astro 1 or 2, note that it has been moved to this external package starting in version 3. Replace your imports accordingly.