github-markdown-css: GitHub's Markdown styling as a standalone stylesheet

The problem: your Markdown renders, but it does not look like GitHub

Markdown parsers produce plain semantic HTML. Headings, tables, nested lists and fenced code blocks all come out as unstyled elements, so a README that looks tidy on github.com turns into browser defaults once you render it yourself. Writing that typography by hand means matching GitHub's font stack, its spacing between blocks, its table borders, its blockquote treatment and its code block backgrounds, and then doing it again for dark mode.

github-markdown-css exists to skip that work. It is a stylesheet, not a parser and not a component library. You render Markdown to HTML with whatever tool you already use, wrap the output in an element with the markdown-body class, and load the CSS. The README describes it as "the minimal amount of CSS to replicate the GitHub Markdown style", and the package ships seven files so the same markup can be shown in light, dark, dimmed, high-contrast and colorblind variants.

The audience is narrow but real: people building documentation sites, changelog pages, comment threads, static site generators, or email and PDF previews where the reader expects GitHub's visual conventions. If your goal is a custom brand identity, this is the wrong starting point.

How the package is structured: seven CSS files and one class name

The repository root holds the seven stylesheets listed in package.json's files array: github-markdown.css, github-markdown-light.css, github-markdown-dark.css, github-markdown-dark-dimmed.css, github-markdown-dark-high-contrast.css, github-markdown-dark-colorblind.css and github-markdown-light-colorblind.css. The default file is the one that switches automatically, using @media (prefers-color-scheme), while the others pin a single theme.

The contract is a single class. Everything in the stylesheet hangs off .markdown-body, so the CSS does not leak into your navigation, sidebar or footer unless you put those elements inside the container. That is the main reason this is easy to drop into an existing page: you are not adopting a global reset.

The files are generated, not hand-written. The README states plainly that contributions should go to sindresorhus/generate-github-markdown-css, and package.json shows how: each theme is produced by running the github-markdown-css CLI with a --theme value (light, dark, dark_dimmed, dark_high_contrast, dark_colorblind, light_colorblind, auto) and redirecting stdout into a file. The make script chains all seven. This matters for anyone planning to fork: editing the CSS in this repository is editing build output, and the next regeneration overwrites it.

Installing github-markdown-css and rendering a first page

The README gives three routes: download the file manually from the gh-pages branch, take it from CDNJS, or install with npm. The npm route pulls the seven CSS files into node_modules and exposes github-markdown.css as the package main.

npm install github-markdown-css

After that, copy or link the stylesheet into your page and add the class. The README's own example sets a viewport meta tag, a box-sizing rule, a min-width of 200px, a max-width of 980px, centered margins, and 45px of padding, with 15px padding below 767px. Those numbers are the ones GitHub uses, so copying them keeps the proportions familiar.

<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="github-markdown.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;
		}
	}
</style>
<article class="markdown-body">
	<h1>Unicorns</h1>
	<p>All the things</p>
</article>

What you should see is a heading and paragraph styled like a GitHub README, with the container capped at 980px. To force one theme instead of the automatic switch, point the link at github-markdown-light.css or github-markdown-dark.css. If you want the HTML itself to match what GitHub produces, the README points at GitHub's /markdown API, and for code block highlighting it suggests starry-night alongside your parser.

Quirks mode is the failure you will actually hit

The troubleshooting section names one specific symptom: tables in dark mode rendering their fonts in black. The cause it gives is not the stylesheet but the document, which the browser may be parsing in quirks mode. The fix is a doctype at the top of the page.

<!doctype html>
<html lang="en"><head></head><body></body></html>

This is worth taking seriously because the failure looks like a CSS bug and sends people hunting through the theme files. If your Markdown content is injected into a page fragment, an iframe, or a template that strips the doctype, you can lose standards mode without noticing until a dark theme is applied.

The second limitation is scope. The stylesheet styles rendered Markdown, not the editor that produces it. There is no JavaScript, no syntax highlighter and no parser in the package, so a toolbar, live preview or drag-and-drop image handling is entirely your problem. The README also notes that parsers other than GitHub's will "mostly" work, which is an honest hedge: parsers that emit different markup for footnotes, task lists or admonitions will not be covered by rules written for GitHub's output.

Alternatives: highlight.js themes and full CSS frameworks

The closest comparison is a syntax highlighting theme such as the ones shipped with highlight.js or Prism. Those style the code inside a block, with token colors for keywords, strings and comments. github-markdown-css styles the block itself, along with headings, lists, tables, blockquotes and the rest of the document. The two solve different halves of the same page, which is why the README suggests pairing this stylesheet with starry-night rather than treating highlighting as part of the package.

The other comparison is a general CSS framework. Frameworks give you a grid, buttons, form controls and a component vocabulary you can restyle. This package gives you one class and no components. If you need a design system, a framework is the better base and you would spend more time overriding github-markdown-css than using it. If you need a rendered README to look like a rendered README, the framework is more surface area than the job requires.

Maintenance, licence and the cost of regenerating CSS

The last push to the repository was on 2026-09-18, and the most recent release listed is v5.9.0 from 2026-02-03. The repository is not archived. Because the CSS is generated upstream, the practical upgrade path is to bump the npm version and replace the file you copied, rather than to patch rules in place. Any local edits you make to a theme file will be lost on the next update, so customizations belong in a separate stylesheet loaded after this one.

The package is MIT licensed, and package.json declares the same identifier. That is permissive and widely compatible, but the licence covers the CSS files in this repository; it does not grant you rights to GitHub's trademarks, logos or interface assets, and it says nothing about the terms of GitHub's /markdown API, which is a separate service you would be calling. The repository also carries a funding link in package.json. None of this is legal advice; read the licence file and the API terms yourself if the distinction matters to your product.

Editorial conclusion

Adopt github-markdown-css if you render Markdown to HTML and want it to look like GitHub without writing typography rules yourself, especially if you already use GitHub's /markdown API or starry-night for code highlighting. Do not adopt it if you need a design system you can extend, or if you want the upstream project to accept your CSS changes: the README states the CSS is generated and contributions belong in sindresorhus/generate-github-markdown-css. Before shipping, verify that your page starts with a doctype, since the troubleshooting section ties dark-mode table bugs to quirks mode, and check which of the seven theme files matches the GitHub theme you are imitating.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sindresorhus/github-markdown-css on GitHub