Markdown CSS Themes: Style Markdown Like GitHub
September 11, 2026 · 9 min read
Markdown CSS Themes: Style Rendered Markdown Like GitHub
Markdown CSS themes are stylesheets you apply to the HTML a Markdown renderer produces, because Markdown itself carries no styling. The fastest route to a GitHub look is github-markdown-css: wrap the output in a .markdown-body container, link one file, and add a width. This guide gives you that template, then covers code highlighting, theme collections, Pandoc, and VS Code.
Why Markdown Styling Happens in CSS, Not in Markdown
Markdown has no concept of fonts, colors, or spacing. A converter turns # Title into <h1>Title</h1> and **bold** into <strong>bold</strong>, and that HTML is what a browser paints. Any markdown styling you see, on GitHub or in an editor preview, is CSS applied to those tags. The markdown styles are never in the file itself. The Markdown vs HTML comparison goes deeper into that split.
That has two practical consequences. First, a stylesheet written for one renderer mostly works with another, because h1, p, code, and table are the same tags everywhere. Second, you usually scope the styles to a container class so they don't leak into your site's header and footer. Almost every markdown css theme uses a wrapper such as .markdown-body for exactly that reason.
If you want a single word to change color inside the text rather than restyling the whole page, that's a different problem. The text color guide covers the inline HTML tricks; this post is only about stylesheets.
GitHub Markdown CSS: A Paste-Ready Template
The github-markdown-css package by Sindre Sorhus is generated from GitHub's own styles and is the most widely used of the markdown-css themes. Searches for github markdown-css or github-markdown css both land on it. Its README tells you to add a markdown-body class to the container and set a width yourself: GitHub uses 980px with 45px of padding, and 15px on mobile. Here's a complete page that loads version 5.9.0 from cdnjs:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.9.0/github-markdown.min.css">
<style>
.markdown-body {
box-sizing: border-box;
min-width: 200px;
max-width: 980px;
margin: 0 auto;
padding: 45px;
}
@media (max-width: 767px) {
.markdown-body { padding: 15px; }
}
@media (prefers-color-scheme: dark) {
body { background-color: #0d1117; }
}
</style>
</head>
<body>
<article class="markdown-body">
<!-- paste the HTML from your converter here -->
<h1>Project notes</h1>
<p>Rendered with <code>github-markdown.css</code>.</p>
</article>
</body>
</html>
Three details in that template matter. The doctype prevents quirks mode, which the README lists as the cause of dark-mode tables rendering with black text. The prefers-color-scheme rule sets the page background to match the dark theme, since the stylesheet only styles the article. And the padding values are yours to change; the package deliberately leaves layout to you.
The HTML inside the article comes from any converter. Our Markdown to HTML tool outputs the body markup, and the conversion guide covers the command-line options.
Which github-markdown-css file should you load?
The package ships seven stylesheets. Pick by how you want light and dark handled:
| File | Behaviour |
|---|---|
github-markdown.css | Switches between light and dark automatically with prefers-color-scheme |
github-markdown-light.css | Light only |
github-markdown-dark.css | Dark only |
github-markdown-dark-dimmed.css | GitHub's dimmed dark palette |
github-markdown-dark-high-contrast.css | Dark with higher contrast |
github-markdown-dark-colorblind.css | Dark, tuned for protanopia and deuteranopia |
github-markdown-light-colorblind.css | Light, tuned for protanopia and deuteranopia |
We prefer the automatic file for documentation sites and the light-only file for anything that gets printed, because you don't want a dark background on paper. Swap the filename in the cdnjs URL to change themes; the version number stays the same.
Try the Markdown that the stylesheet will style
Paste your own document below to see the plain rendered output. The preview is what a theme receives: headings, paragraphs, a table, and a code block, with no styling decisions made for you yet.
Do Code Blocks Need Their Own Markdown CSS Theme?
Yes, and this is the step most tutorials skip. A Markdown theme styles the pre and code boxes: background, font, padding. It does not color keywords, strings, or comments inside them. Syntax colors come from a highlighter that wraps tokens in span elements, and the highlighter has its own stylesheet.
The github-markdown-css README recommends starry-night for GitHub-identical highlighting, because it uses the same grammars GitHub does and ships CSS that works with the theme. highlight.js and Prism work as well, each with dozens of themes. Whichever you pick, the page ends up with two stylesheets: one for the document and one for the tokens. Our code block guide explains the language tag that tells the highlighter what to color.
One limitation to plan for: highlighting happens either at conversion time (the converter emits the spans) or in the browser with JavaScript. A static stylesheet alone can't add it.
Where Do Markdown CSS Themes Come From?
Beyond the GitHub clone, a handful of collections cover most tastes. All of them use the same mechanic: link the file, wrap the content, adjust the width.
jasonm23/markdown-css-themes is the repository that ranks for the phrase. It's a curated list linking to live previews of dozens of markdown-css themes rather than a package you install, and its last update was in 2022. Use it as a gallery, then grab the stylesheet you like from its source.
markdowncss.github.io offers four minimalist themes: Splendor, Retro, Air, and Modest. Each lives in its own repository and npm package (for example markdown-air and markdown-modest). They haven't changed much since 2015 to 2022, which is fine for CSS this small, but expect no dark-mode variants.
markdown-styles by mixu is a generator plus a theme set, published on npm at version 3.2.0. It converts a folder of Markdown to HTML with a chosen theme in one command, so it suits people who don't want to hand-write the template above.
Dracula publishes a Markdown CSS variant of its dark palette for people who already use the theme in their editor.
Two more sources are worth knowing. Static site generators such as Hugo and Jekyll ship themes with Markdown styling already wired in. If you publish through one of those, you rarely need a separate stylesheet. And any GitHub Pages site with the default theme is using GitHub's own markdown-css themes indirectly, which is why pages there look like READMEs.
Which one you pick matters less than getting the wrapper class right. A theme that expects .markdown-body does nothing if your container is called .content.
Markdown Styling in Pandoc, VS Code, and PDF Export
The same stylesheets apply outside the browser, with one flag or setting each.
Pandoc. Pass --css (short form -c) with a path or URL. The Pandoc manual notes that the option only affects HTML and EPUB output and can be repeated for multiple files. Combine it with --standalone, because the link tag goes in the document head and a fragment has no head:
pandoc notes.md -s --css github-markdown.css -o notes.html
Wrap the body in the theme's container by supplying a template, or add a small rule mapping body to the same styles.
VS Code. The built-in preview accepts your own stylesheets through the markdown.styles setting. The VS Code Markdown docs describe it as a list of https URLs or workspace-relative paths:
{
"markdown.styles": ["https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.9.0/github-markdown.min.css"]
}
VS Code's preview uses its own body classes rather than markdown-body, so styles scoped to that class won't apply until you add a rule such as body { ... } in a second local file or use a theme that styles bare tags.
PDF. Browser-based PDF export is HTML plus CSS under the hood, so any theme that looks right on screen prints the same way. Add an @media print block for page margins and page breaks. Our Markdown to PDF converter handles the HTML and print steps for you if you'd rather skip the setup.
Common Markdown Styling Mistakes
Forgetting the wrapper class. github-markdown-css scopes everything under .markdown-body. Load the file, skip the class, and nothing changes. Check the element inspector for the class before you blame the CDN.
Expecting the theme to set a page width. The package intentionally leaves max-width and padding to you. Without them, paragraphs stretch across the whole window and line lengths become hard to read.
Loading a document theme and wondering why code isn't colored. Syntax colors need a highlighter and its stylesheet. Two files, not one.
Markdown CSS Themes FAQ
Once you understand that markdown CSS themes style HTML rather than Markdown, every setup looks the same: convert, wrap, link, size. Start with github-markdown-css 5.9.0 from cdnjs, add a highlighter theme for code, and reuse the same file in Pandoc and VS Code. Draft the document in the editor, export the HTML, and drop it into the template above.