Apply GitHub’s Markdown Styling to Tailwind – tailwindcss-github-markdown

tailwindcss-github-markdown is a Tailwind CSS plugin that allows you to apply GitHub’s Markdown styling to your projects.

It provides a simple way to achieve the familiar and polished look of GitHub-rendered Markdown content directly within your Tailwind CSS workflow.

Features

Use Cases

• Project Documentation: Display README.md files or other Markdown-based documentation directly in your web projects with GitHub’s styling.
• Blog Posts: Render blog articles written in Markdown with a clean, professional, and familiar appearance.
• Comment Sections: Style user-generated Markdown comments to look like GitHub issues or discussions.
• Knowledge Bases: Format Markdown content in internal wikis or knowledge bases with a developer-friendly aesthetic.

Installation

Install the plugin via a package manager.

pnpm add -D tailwindcss-github-markdown

Add the plugin to your CSS file.

/* styles.css */
@import 'tailwindcss';
@plugin 'tailwindcss-github-markdown';

Ensure your Tailwind CSS setup is correctly configured to process this plugin.

Usage

Add the prose class to the HTML element that contains your Markdown-rendered content. For dark mode compatibility, you can also add the dark:prose-invert class.

Here are examples for different environments:

HTML:

<div class="prose dark:prose-invert">
  <!-- Your Markdown content here -->
</div>

React/Next.js:

<div className="prose dark:prose-invert">{/* Your Markdown content here */}</div>

Vue:

<template>
  <div class="prose dark:prose-invert">
    <!-- Your Markdown content here -->
  </div>
</template>

The dark:prose-invert class activates the dark theme styles when a parent element has the dark class or if the user’s system preference is set to dark mode (assuming Tailwind’s darkMode: 'media' option is configured).

You can customize the default styles by overriding them in your own CSS. Since all plugin styles are scoped to the .prose class, you can target specific elements within it. For example, to change link colors:

.prose a {
  @apply text-primary underline; /* Ensure 'text-primary' is defined in your Tailwind config */
}
.prose a:hover {
  @apply text-primary/90; /* Example of using an opacity modifier */
}

Related Resources

• @tailwindcss/typography – The official Tailwind typography plugin that provides general prose styling (different from GitHub’s specific style)
  https://tailwindcss.com/docs/typography-plugin
• GitHub Markdown CSS – Stand-alone CSS implementation of GitHub’s markdown styles (non-Tailwind version)
  https://github.com/sindresorhus/github-markdown-css
• react-markdown – Popular React component for rendering Markdown (pairs well with this styling plugin)
  https://github.com/remarkjs/react-markdown

FAQs

Q: How is tailwindcss-github-markdown different from @tailwindcss/typography?
A: tailwindcss-github-markdown specifically aims to replicate GitHub’s Markdown styling. @tailwindcss/typography provides its own set of opinionated typographic defaults which are not tied to GitHub’s look.

Q: Does this plugin support dark mode automatically based on system preference?
A: Yes, if you use the dark:prose-invert class and have Tailwind CSS’s dark mode set to 'media' in your tailwind.config.js file, it will respond to system preferences.

Q: Can I customize the styles applied by tailwindcss-github-markdown?
A: Yes, you can override the default styles by targeting selectors within the .prose class in your own CSS file.

Q: Do I need any other libraries to use this plugin?
A: You need Tailwind CSS installed and configured in your project. This plugin styles HTML, so you will also need a way to convert your Markdown to HTML (e.g., using a library like Marked.js or an integrated feature of your framework/static site generator).

Q: Will this plugin affect other parts of my website’s styling?
A: The styles are scoped to elements with the prose (or prose-invert) class, so it should not interfere with your other website styles unless they also use these specific classes in a conflicting manner.

Q: How do I handle custom code block syntax highlighting?
A: This plugin handles the base styling of code blocks, but you’ll need to add a syntax highlighter like Prism.js or highlight.js for language-specific syntax highlighting.

Preview