Adding Markdown Without MDX

Astro supports two paths for enhancing Markdown in a project: MDX, or a Markdown Component. This piece covers the latter. Its two practical benefits are that it cuts down the amount of markup you have to write, and that it converts typographic symbols such as ' into proper opening or closing quotes.

With it, a whole set of HTML tags becomes optional — <p>, <strong>, <em>, <ul>, <ol>, <li>, and <a>. Heading tags can be skipped too, provided you don't need to attach classes to them.

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

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

The prettier-ignore comment keeps Prettier from formatting the contents of the <Markdown> block, so your Markdown survives a save intact. The markup above renders like this:

<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 the second paragraph with a <a href="https://link-somewhere.com">link</a></p>

  <ul>
    <li> List </li>
    <li> Of </li>
    <li> Items </li>
  </ul>
</div>

History and Installation

Astro shipped with a <Markdown> component in its early releases, but it was moved to a separate plugin in version 1 and removed completely in version 3. Using a component like this one is a matter of importing it and then applying it as shown above.

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

<Markdown>
  ...
</Markdown>

Indentation and the Inline Option

Content can be written the way you'd normally write it: the component detects indentation on its own and outputs the correct values, without wrapping them in <pre> and <code> tags.

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

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

The resulting output:

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

An inline option instructs the <Markdown> component to skip generating paragraph tags.

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

And its output:

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

Known Issues With Prettier

Prettier breaks the <!-- prettier-ignore --> block whenever unicode characters such as emojis or em dashes appear anywhere ahead of it. Given the original code:

<!-- prettier-ignore -->
<Markdown>
  Markdown block that contains Unicode characters 🤗
</Markdown>

<!-- prettier-ignore -->
<Markdown>
  Second Markdown block.
</Markdown>

saving produces this:

<!-- prettier-ignore -->
<Markdown>
  Markdown block that contains unicode characters 🤗
</Markdown>

<!-- prettier-ignore -->
<Markdown>
  Second Markdown block.
</Markdown>

Emojis can't be worked around here, since the root cause sits in Prettier's formatter. Dashes are manageable: write -- for an en dash and --- for an em dash.

Passing Content Through the content Property

A second route avoids the <!-- prettier-ignore --> comments entirely: place the content inside a content property instead. Whitespace is handled for you.

<Markdown content=`
  This is a paragraph

  This is another paragraph
`/>

This approach reads less cleanly than the slot version, but it lets you pass Markdown directly alongside any JS or JSON content you load.

---
const content = `
  This is a paragraph

  This is another paragraph
`
---

<Markdown {content} />