All Articles

Showcasing the power of MDX

A

Renas Hassan

Apr 28th, 2024

Until now, trying to style an article, document, or blog post with Tailwind has been a tedious task that required a keen eye for typography and a lot of complex custom CSS.

By default, Tailwind removes all of the default browser styling from paragraphs, headings, lists and more. This ends up being really useful for building application UIs because you spend less time undoing user-agent styles, but when you really are just trying to style some content that came from a rich-text editor in a CMS or a markdown file, it can be surprising and unintuitive.

We get lots of complaints about it actually, with people regularly asking us things like:

Why is Tailwind removing the default styles on my h1 elements? How do I disable this? What do you mean I lose all the other base styles too?

We hear you, but we're not convinced that simply disabling our base styles is what you really want. You don't want to have to remove annoying margins every time you use a p element in a piece of your dashboard UI. And I doubt you really want your blog posts to use the user-agent styles either — you want them to look awesome, not awful.

The @tailwindcss/typography plugin is our attempt to give you what you actually want, without any of the downsides of doing something stupid like disabling our base styles.

It adds a new prose class that you can slap on any block of vanilla HTML content and turn it into a beautiful, well-formatted document:

<article class="prose">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread with cheese to their
    children, with the food earning such an iconic status in our culture that kids will often dress
    up as warm, cheesy loaf for Halloween.
  </p>
  <p>
    But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
    springing up around the country.
  </p>
  <!-- ... -->
</article>

What to expect from here on out

What follows from here is just a bunch of absolute nonsense I've written to dogfood the plugin itself. It includes every sensible typographic element I could think of, like bold text, unordered lists, ordered lists, code blocks, block quotes, and even italics.

It's important to cover all of these use cases for a few reasons:

1. We want everything to look good out of the box.
2. Really just the first reason, that's the whole point of the plugin.
3. Here's a third pretend reason though a list with three items looks more realistic than a list with two items.

Now we're going to try out another header style.

Typography should be easy

So that's a header for you — with any luck if we've done our job correctly that will look pretty reasonable.

Something a wise person once told me about typography is:

Typography is pretty important if you don't want your stuff to look like trash. Make it good then it won't be bad.

It's probably important that images look okay here by default as well:

Now I'm going to show you an example of an unordered list to make sure that looks good, too:

• So here is the first item in this list.
• In this example we're keeping the items short.
• Later, we'll use longer, more complex list items.

And that's the end of this section.

What if we stack headings?

We should make sure that looks good, too.

Sometimes you have headings directly underneath each other. In those cases you often have to undo the top margin on the second heading because it usually looks better for the headings to be closer together than a paragraph followed by a heading should be.

Code should look okay by default.

We've already installed the plugin, so we should be able to just drop in a code block and have it look good. You can also customize it to match your VSCode theme.

export async function BlogPage() {
  const articles = await getArticles("blog")

  return (
    <Container className="flex max-w-7xl flex-col gap-6">
      <Typography variant="h1">Blog</Typography>
      <SearchArticle articles={articles} />
      <Typography variant="h2">Latest Articles</Typography>
      <Articles articles={articles} />
    </Container>
  )
}

There are other elements we need to style

We even included table styles, check it out:

We haven't used an h4 yet

But now we have. Please don't use h5 or h6 in your content, Medium only supports two heading levels for a reason, you animals. I honestly considered using a before pseudo-element to scream at you if you use an h5 or h6.

We don't style them at all out of the box because h4 elements are already so small that they are the same size as the body copy. What are we supposed to do with an h5, make it smaller than the body copy? No thanks.

Conclusion

That's it. That's the whole plugin. It's not rocket science, but it's a huge time-saver. We hope you like it. This is all just a bunch of nonsense I wrote to test the plugin, but it should give you a good idea of what to expect when you use it for real content.

This was all written in MDX, by the way. If you're not using MDX yet, you should be. It's awesome.