How to Supercharge Your Astro Site with a Custom Markdown Component
By ✦ min read
<h2>Introduction</h2>
<p>Working with Markdown inside Astro components can save you time and reduce clutter. Instead of wrapping each line in <code><p></code>, <code><strong></code>, or <code><em></code>, 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 <em>inline</em> option and how to keep Prettier from messing up your syntax.</p><figure style="margin:20px 0"><img src="https://i0.wp.com/css-tricks.com/wp-content/uploads/2026/02/markdown-astro.webp" alt="How to Supercharge Your Astro Site with a Custom Markdown Component" style="width:100%;height:auto;border-radius:8px" loading="lazy"><figcaption style="font-size:12px;color:#666;margin-top:5px">Source: css-tricks.com</figcaption></figure>
<h2>What You Need</h2>
<ul>
<li>An existing Astro project (version 3 or higher recommended)</li>
<li>Node.js (v16 or later)</li>
<li>Basic familiarity with Astro components and Markdown syntax</li>
<li>A package manager: npm, yarn, pnpm, or bun</li>
</ul>
<h2>Step-by-Step Instructions</h2>
<h3 id="step-1">Step 1: Understand What a Markdown Component Does</h3>
<p>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.</p>
<p>Originally, Astro had a built-in <code><Markdown></code> component, but it was moved to an external package in version 1 and removed entirely in version 3. The community-maintained <code>@splendidlabz/astro</code> package provides a drop-in replacement.</p>
<h3 id="step-2">Step 2: Install the Markdown Component Package</h3>
<p>Open your terminal, navigate to your Astro project root, and install the package using your preferred package manager:</p>
<pre><code class="language-bash">npm install @splendidlabz/astro</code></pre>
<p><em>or</em></p>
<pre><code class="language-bash">yarn add @splendidlabz/astro</code></pre>
<p>Once installed, the <code><Markdown></code> component will be available for import.</p>
<h3 id="step-3">Step 3: Import and Use the Component</h3>
<p>In any Astro component (<code>.astro</code> file), add the import at the top of the frontmatter:</p>
<pre><code class="language-astro">---
import { Markdown } from '@splendidlabz/astro';
---</code></pre>
<p>Then use it anywhere in your template. Surround your Markdown content with the opening and closing tags:</p>
<pre><code class="language-astro"><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></code></pre>
<p>The component will output standard HTML tags, making your content semantic and accessible without extra markup.</p>
<h3 id="step-4">Step 4: Take Advantage of Automatic Indentation Handling</h3>
<p>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 <code><pre></code> or <code><code></code> tags. For example:</p>
<pre><code class="language-astro"><section>
<article>
<Markdown>
This is the first paragraph.
This is the second paragraph.
</Markdown>
</article>
</section></code></pre>
<p>The output will be clean, with each paragraph wrapped in <code><p></code> tags and no unwanted extra indentation.</p>
<h3 id="step-5">Step 5: Use the Inline Option for Short Snippets</h3>
<p>Sometimes you only need to apply Markdown inline formatting — like bold or italic — inside a heading or a single element. Use the <code>inline</code> prop to suppress the automatic paragraph wrapping:</p>
<pre><code class="language-astro"><h2 class="max-w-2xl">
<Markdown inline> Ain't this cool? </Markdown>
</h2></code></pre>
<p>This outputs:</p>
<pre><code class="language-html"><h2 class="max-w-2xl">
Ain't this cool?
</h2></code></pre>
<p>Notice that the apostrophe was converted to a curly right single quote automatically.</p>
<h3 id="step-6">Step 6: Prevent Prettier from Ruining Your Markdown</h3>
<p>Prettier, a popular code formatter, may try to reformat the contents inside the <code><Markdown></code> block, which can break intentional spacing or indentation. To avoid this, add an HTML comment <code><!-- prettier-ignore --></code> just before the opening <code><Markdown></code> tag:</p>
<pre><code class="language-astro"><div>
<!-- prettier-ignore -->
<Markdown>
This will stay exactly as I wrote it.
- Not
- Reformatted
</Markdown>
</div></code></pre>
<p>This tells Prettier to skip formatting that block, preserving your Markdown structure.</p>
<h2>Tips & Best Practices</h2>
<ul>
<li><strong>Keep it simple:</strong> Use the Markdown component for content-heavy sections like blog posts, cards, or documentation blocks. For simple text, plain HTML is often faster.</li>
<li><strong>Combine with Typography:</strong> The component automatically handles smart quotes and dashes — no extra plugins needed.</li>
<li><strong>Be careful with headings:</strong> If you need to add classes to headings, you can still use <code><h2 class="..."></code> 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.</li>
<li><strong>Always use <code><!-- prettier-ignore --></code></strong> if your project uses Prettier, especially when the Markdown block is deeply nested.</li>
<li><strong>Check your version:</strong> The <code>@splendidlabz/astro</code> package works with Astro 3+. If you’re on an older version, consider upgrading or using a different approach.</li>
<li><strong>Don’t over-nest:</strong> While the component handles indentation, deeply nested Markdown inside multiple divs can be harder to read. Keep your structure shallow when possible.</li>
</ul>
Tags: