generate-github-markdown-css User Guide

generate-github-markdown-css is a Node.js CLI and ES-module library that scrapes GitHub.com directly to produce a self-contained CSS stylesheet matching how GitHub renders Markdown. It is the upstream generator behind the popular static github-markdown-css package — instead of consuming a snapshot, you regenerate the stylesheet on demand against the live GitHub UI, picking the exact theme(s) you want and the scoping selector you need.

The tool fetches the GitHub repository page, harvests every linked CSS file, parses each with PostCSS, filters the rules through an allow-list of HTML tags and CSS classes that GitHub uses for Markdown rendering, runs a rendered-fixture pass through GitHub's public Markdown API to capture dynamically-generated classes, and writes a single stylesheet to stdout. The output works in any environment where you display GFM-flavored content: documentation portals, static-site generators, custom Markdown viewers, browser extensions, embedded dashboards, and anywhere else you want pages that look like a GitHub README.md.

This guide covers everything you need to use it as an end user — from a one-line npx invocation to library integration in a build pipeline.

1. Quick Start

The lowest-friction way to get a stylesheet is one command, no install:

npx generate-github-markdown-css > github-markdown.css

Drop the resulting file into your project, link it from your HTML, and wrap your rendered Markdown in <article class="markdown-body">…</article>. That's the whole flow.

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="github-markdown.css">
  </head>
  <body>
    <article class="markdown-body">
      <!-- your rendered HTML goes here -->
    </article>
  </body>
</html>

Tip

The default invocation produces an "auto" stylesheet that adapts to the user's prefers-color-scheme setting — light theme during the day, dark theme at night, with no JavaScript required. If you only want one fixed theme, pass --theme=light or --theme=dark.

Key features

• Single-binary CLI plus a JavaScript library — same code, two surfaces.
• Six built-in themes: light, dark, dark_dimmed, dark_high_contrast, dark_colorblind, light_colorblind.
• Auto mode emits prefers-color-scheme blocks so one stylesheet handles light and dark.
• Single mode emits a flat stylesheet with all CSS variables already inlined.
• Decouple variables from styles via --only-variables and --only-style so you can ship one base stylesheet plus swappable theme-variable files.
• Custom root selector lets you scope rules to anything other than .markdown-body.
• Transparent background mode for embedding inside themed pages.
• Disk cache (node_modules/.cache/generate-github-markdown-css/) makes re-runs fast and keeps GitHub fetch traffic low.

Prerequisites

Node.js 18 or later (declared in package.json engines.node). The tool itself has only two runtime dependencies: meow for CLI parsing and postcss for CSS transformation.

Verify the install

npx generate-github-markdown-css --list

light
dark
dark_dimmed
dark_high_contrast
dark_colorblind
light_colorblind

If you see those six names, the network fetch and CSS parsing both succeeded — you're ready to generate stylesheets.

What to try next

• See the Common Tasks section for theme variants, scoped selectors, and CI patterns.
• See the Configuration section for every CLI flag and JS option.
• See the Troubleshooting section if --list fails or the output looks wrong.

2. Installation

Pick a method based on how often you'll regenerate the CSS and whether you want to call the library from JavaScript.

Method 1 — npx (recommended for one-offs and CI)

Zero install. Always pulls the current version from the npm registry. Best for occasional regeneration and reproducible CI jobs:

npx generate-github-markdown-css > github-markdown.css

Tip

Pin the version in CI for reproducible output: npx generate-github-markdown-css@6.6.0 > github-markdown.css.

Method 2 — Global install

Install once, run anywhere on your machine. Best when you regenerate stylesheets across many projects:

npm install --global generate-github-markdown-css

After install, the binary is on your PATH as github-markdown-css:

github-markdown-css > github-markdown.css
github-markdown-css --list

Method 3 — Project dependency (library use)

Install as a dev dependency when you want to call it programmatically from a build script, an Eleventy/Hugo plugin, or your own tooling:

npm install --save-dev generate-github-markdown-css

Then import and call it from any ES module:

import githubMarkdownCss from 'generate-github-markdown-css';
import fs from 'node:fs';

const css = await githubMarkdownCss();
fs.writeFileSync('public/github-markdown.css', css);

Important

The package is ES-module only — the package.json declares "type": "module" and exports a single default export. If your project is CommonJS, use a dynamic await import('generate-github-markdown-css') or convert your build script to ESM. There is no require() shim.

Method 4 — From source (for contributors)

git clone https://github.com/sindresorhus/generate-github-markdown-css.git
cd generate-github-markdown-css
npm install
node cli.js --list

This is only necessary if you intend to modify index.js, add a theme, or run the test harness (npm test). For all consumption use cases, prefer methods 1–3.

Verifying installation

Warning

Every run reaches out to github.com over HTTPS. If you're behind a corporate proxy, set HTTPS_PROXY in your environment so Node's built-in fetch can reach GitHub. There is no offline mode — see the Troubleshooting section if your network blocks GitHub.

3. Configuration

The tool has no configuration file. All behaviour is controlled by CLI flags or by the options object passed to the JavaScript API. The two surfaces map one-to-one.

CLI flags (complete list)

JS API options (complete list)

The default export of generate-github-markdown-css is an async function that takes one options object and returns a string of CSS (or, with list: true, a newline-delimited list of theme names).

Note

The CLI flag is --only-style (singular) but the JS option is onlyStyles (plural). The CLI shim in cli.js maps onlyStyle from meow to onlyStyles when calling the library. Keep this in mind when porting examples between the two surfaces.

Modes — auto vs single

The tool operates in two output modes, and which one you get is a function of the light/dark values you supply:

Important

Auto mode always preserves CSS variables — they are required by the prefers-color-scheme blocks. --preserve-variables only matters in single mode, where it controls whether you get inline values or var() references.

Available themes

The full theme list is fetched live from GitHub and may evolve. As of commit 58d00ca, the six themes returned by --list are:

Note

Always run --list before scripting against a specific theme name — GitHub adds and renames themes over time, and the tool reports whatever the live page exposes.

Environment variables

The tool reads no custom environment variables. Standard Node.js variables apply:

• HTTPS_PROXY / HTTP_PROXY — used by Node's built-in fetch when set.
• NODE_OPTIONS — Node runtime tuning (rarely needed; the tool is light).

4. Core Usage

One-shot stylesheet (the default)

npx generate-github-markdown-css > github-markdown.css

Produces an auto-mode stylesheet using the light and dark defaults. The output starts with a hoisted shared-variables block, then a @media (prefers-color-scheme: light) block, then a @media (prefers-color-scheme: dark) block, then the rule definitions.

Forcing a single theme

npx generate-github-markdown-css --theme=dark > github-markdown.css

npx generate-github-markdown-css --theme=dark_dimmed > github-markdown.css

--theme=<name> is a shortcut for --light=<name> --dark=<name> and produces a single-mode stylesheet with the variables inlined.

Listing themes

github-markdown-css --list

light
dark
dark_dimmed
dark_high_contrast
dark_colorblind
light_colorblind

Calling from JavaScript

import githubMarkdownCss from 'generate-github-markdown-css';

// Default (auto mode, light + dark)
const cssAuto = await githubMarkdownCss();

// Single theme, inlined values
const cssDark = await githubMarkdownCss({light: 'dark', dark: 'dark'});

// Just the variable definitions for two themes
const vars = await githubMarkdownCss({
  light: 'light_colorblind',
  dark: 'dark_colorblind',
  onlyVariables: true,
});

// Just the rules, no variables
const baseStyles = await githubMarkdownCss({onlyStyles: true});

Tip

The function returns a Promise<string> — always await it. Forgetting await and writing the promise to disk produces a .css file containing the literal text [object Promise].

Scoping the rules

Replace .markdown-body with anything you like:

npx generate-github-markdown-css --root-selector='.my-doc' > my-doc.css

Every selector in the output that contained .markdown-body will be rewritten to use .my-doc. The replacement is a literal string substitution applied after the CSS is built.

Transparent background

Useful when embedding rendered Markdown inside a parent page that already has a styled background:

npx generate-github-markdown-css --transparent-background > github-markdown.css

The rule that would normally set background-color: var(--bgColor-default) becomes background-color: transparent (or the variable itself becomes transparent in modes that preserve variables).

Note

--transparent-background only changes the body background. Code blocks, tables, and other elements keep their normal backgrounds.

5. Common Tasks

5.1 Generate the default light + dark stylesheet

npx generate-github-markdown-css > github-markdown.css

The result adapts to prefers-color-scheme. Reference it with a single <link> tag and you support both light and dark mode automatically.

5.2 Generate a fixed dark theme

npx generate-github-markdown-css --theme=dark > github-markdown-dark.css

Produces a flat stylesheet pinned to the dark theme. No prefers-color-scheme blocks. Use when your app forces a single theme regardless of OS preference.

5.3 Generate a high-contrast variant for accessibility

npx generate-github-markdown-css --theme=dark_high_contrast > github-markdown-hc.css

Pair this with a user setting that toggles between the standard stylesheet and this one when an "accessibility / high contrast" preference is active.

// Example browser hook
document.querySelector('#md-stylesheet').href =
  prefersHighContrast ? '/css/github-markdown-hc.css' : '/css/github-markdown.css';

5.4 Generate a colorblind-friendly auto stylesheet

npx generate-github-markdown-css --light=light_colorblind --dark=dark_colorblind > github-markdown-cb.css

You get a prefers-color-scheme-aware stylesheet that uses the colorblind palettes in both light and dark.

5.5 Scope every rule to a custom selector

npx generate-github-markdown-css --root-selector='.docs-prose' > docs-prose.css

Every selector switches from .markdown-body to .docs-prose. Wrap your Markdown output in <div class="docs-prose">…</div> and the rules apply only there. This is the standard pattern for embedding GitHub-styled Markdown inside an app that already has its own design system.

Tip

If you need a more selective scoping (e.g. wrapping in #main article.prose), generate with the default selector and post-process with PostCSS or a sed pass — --root-selector only does a literal .markdown-body → <your selector> replacement.

5.6 Use as a Node library inside a build script

A common pattern is a top-level script that regenerates the stylesheet during npm run build:

// scripts/build-css.js
import fs from 'node:fs/promises';
import path from 'node:path';
import githubMarkdownCss from 'generate-github-markdown-css';

const outDir = path.resolve('public/css');
await fs.mkdir(outDir, {recursive: true});

const auto = await githubMarkdownCss();
await fs.writeFile(path.join(outDir, 'github-markdown.css'), auto);

const dark = await githubMarkdownCss({light: 'dark', dark: 'dark'});
await fs.writeFile(path.join(outDir, 'github-markdown-dark.css'), dark);

console.log('Wrote github-markdown.css and github-markdown-dark.css');

Wire it into package.json:

{
  "scripts": {
    "build:css": "node scripts/build-css.js",
    "build": "npm run build:css && next build"
  }
}

5.7 Integrate with a static-site generator

The same generator works under any SSG. Below are three common patterns; in every case you write the stylesheet once at build time and reference it from your template.

Eleventy (.eleventy.js):

import fs from 'node:fs/promises';
import githubMarkdownCss from 'generate-github-markdown-css';

export default function (eleventyConfig) {
  eleventyConfig.on('eleventy.before', async () => {
    const css = await githubMarkdownCss();
    await fs.writeFile('_includes/css/github-markdown.css', css);
  });
}

Hugo (any pre-build script):

# scripts/regenerate-css.sh
npx generate-github-markdown-css > assets/css/github-markdown.css

Jekyll (Rakefile or pre-build hook):

# Run before `bundle exec jekyll build`
npx generate-github-markdown-css > assets/github-markdown.css

In all three, your layout pulls in the stylesheet:

<link rel="stylesheet" href="/assets/github-markdown.css">
<article class="markdown-body">{{ content }}</article>

5.8 Regenerate periodically in CI to track upstream changes

GitHub updates its Markdown CSS without notice. To keep your output in sync, run the generator on a schedule and open a PR if the file changes:

# .github/workflows/refresh-markdown-css.yml
name: Refresh github-markdown.css
on:
  schedule:
    - cron: '0 6 * * 1'    # every Monday at 06:00 UTC
  workflow_dispatch:

jobs:
  refresh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx generate-github-markdown-css@latest > public/github-markdown.css
      - uses: peter-evans/create-pull-request@v6
        with:
          commit-message: 'Refresh github-markdown.css'
          title: 'Refresh github-markdown.css'
          body: 'Auto-generated by the weekly refresh workflow.'
          branch: refresh/github-markdown-css

Warning

Don't run the generator on every page request in production — it makes a live request to github.com and can fail under rate-limiting or network outage. Generate once at build time, ship the output as a static asset, and refresh on a deliberate cadence.

5.9 Decoupled variables and styles (advanced)

For advanced setups where you want one base stylesheet and many swappable theme files:

# Once: the styles, with no embedded variable values
npx generate-github-markdown-css --only-style > base.css

# Once per theme: the variables only
npx generate-github-markdown-css --theme=light --only-variables > vars-light.css
npx generate-github-markdown-css --theme=dark --only-variables > vars-dark.css
npx generate-github-markdown-css --theme=dark_high_contrast --only-variables > vars-hc.css

Then in your HTML, reference base.css plus exactly one variable file at a time. Switching themes is now a one-href change.

<link rel="stylesheet" href="/css/base.css">
<link id="theme" rel="stylesheet" href="/css/vars-dark.css">
<script>
  document.querySelector('#theme').href = `/css/vars-${userTheme}.css`;
</script>

Tip

The repository's own test.js builds exactly this layout (dist/vars/base.css + per-theme *-vars.css) — read it as the canonical example.

6. Troubleshooting

Diagnostic flow when something looks wrong:

1. Does --list return six theme names? If not — network or GitHub-side issue.
2. Did you await the JS API call? If not — output contains [object Promise].
3. Is the markdown wrapped in an element matching your --root-selector (default .markdown-body)? If not — no rules apply.
4. Did you mix --only-variables and --only-style? They are mutually exclusive.
5. Has the disk cache gone stale? Delete node_modules/.cache/generate-github-markdown-css/ and retry.

Error: May not specify onlyVariables and onlyStyles at the same time

Cause: You passed both --only-variables and --only-style (CLI), or both onlyVariables: true and onlyStyles: true (JS API). The combination would produce empty output, so the tool throws instead of running.

Solution:

1. Pick one. Use --only-variables to emit just the variable blocks, or --only-style to emit just the rule definitions.
2. If you want both — that's the default. Run with neither flag.

Prevention: Treat the two flags as mode selectors: pick one or pick neither.

Error: rootSelector may not be an empty string

Cause: You passed --root-selector='' or {rootSelector: ''} to the JS API. An empty selector would replace .markdown-body with nothing, producing invalid CSS.

Solution: Pass any non-empty string. Default is .markdown-body. To use a different scope, write the full selector: --root-selector='.docs'.

Prevention: Quote your shell arguments to avoid accidental empty strings: --root-selector="$SELECTOR" reduces to --root-selector= if $SELECTOR is unset.

Error: Failed to fetch <url>: <body>

Cause: The HTTPS request to github.com (or one of the linked CSS files) returned a non-OK status. This is the failure mode tracked in issue #17 ("currently crashes") when GitHub returns an error page.

Solution:

1. Re-run after a few minutes — transient 5xx and rate-limit responses recover quickly.
2. Check your network can reach github.com (curl -I https://github.com/).
3. If you're behind a corporate proxy, export HTTPS_PROXY.
4. Delete node_modules/.cache/generate-github-markdown-css/ to force a fresh fetch — a corrupted cache file can also surface here.
5. If GitHub has materially changed the page markup, the regex that extracts CSS links may stop matching. Update to the latest version of the generator (npm install --global generate-github-markdown-css@latest or use @latest with npx).

Prevention: Run the generator at build time, not in a hot path. Cache the generated CSS as a static asset.

Error: Failed to render markdown: <body>

Cause: The fixture pass calls https://api.github.com/markdown (the public unauthenticated Markdown rendering endpoint). The endpoint returned a non-OK response — usually rate-limiting on busy CI runners.

Solution:

1. Re-run after a few minutes.
2. If the error is consistent and you don't need fixture-derived classes, skip the fixture: --no-use-fixture (or useFixture: false). The output stylesheet will be slightly smaller but valid.
3. If you regenerate frequently from the same machine, the 7-day fixture cache means you usually only hit the API once a week — if it's failing on every run, the cache write may be blocked. Check write permissions on node_modules/.cache/.

Prevention: Pass --no-use-fixture in environments where you can't reach api.github.com.

Error: Test fails with Error: undefined:1:326905: missing '}'

Cause: Tracked as issue #27. PostCSS rejected the GitHub-served CSS because it was either truncated mid-fetch or contained a construct PostCSS hadn't seen before.

Solution:

1. Delete the cache: rm -rf node_modules/.cache/generate-github-markdown-css/. A truncated *.css.txt will be re-fetched.
2. Update to the latest generator version — PostCSS has been updated multiple times to handle new GitHub CSS features.
3. If reproducible against the latest version, file a new issue with the cached CSS files attached.

Prevention: Don't ship the disk cache as part of your build artifacts.

Output is empty or selectors don't apply

Cause: The most common reason is that your HTML doesn't use the matching root class. The generator output scopes nearly every rule under .markdown-body (or your --root-selector value).

Solution:

1. Wrap your rendered Markdown: <article class="markdown-body">…</article>.
2. If you used --root-selector='.foo', wrap with class="foo" instead.
3. Verify the stylesheet is actually linked — check the network tab for a 200 on the .css URL.

Output contains [object Promise]

Cause: You called the JS API without await:

const css = githubMarkdownCss();          // missing await
fs.writeFileSync('out.css', css);          // writes "[object Promise]"

Solution:

const css = await githubMarkdownCss();
fs.writeFileSync('out.css', css);

Prevention: The function is async. Always await it (or use .then()).

Background colour wrong

Cause: Tracked as issue #16 — the body background is forced to white in light mode and black-ish in dark mode by default.

Solution: Pass --transparent-background (or transparentBackground: true). The body background becomes transparent and inherits whatever the parent page provides.

Prevention: Use --transparent-background whenever you embed the rendered Markdown inside a host page that already has its own background.

Long ordered lists clip the number column

Cause: Tracked as issue #38. Lists with 100+ items have number columns wide enough to overlap the text in some themes.

Solution: This is a GitHub-side rendering quirk; the generator faithfully reproduces it. Workarounds: split the list, increase your container padding-left, or post-process the CSS to widen ol margins.

Colour variables missing

Cause: Tracked as issue #31 — some var(--color-…) references in the live GitHub CSS resolved to nothing because the upstream definitions were removed.

Solution: Update the generator to the latest version (the fix runs var(--fgColor-default, var(--color-fg-default)) through a pass that picks the first form). If you see the issue on the latest version, the GitHub-side names changed again — file a new issue.

7. FAQ

Q: Why does this need to fetch GitHub on every run?

The whole premise is "match GitHub's live rendering." A snapshot-based approach (like the static github-markdown-css package) goes stale every time GitHub ships a CSS change. By fetching the live page on demand, the generator stays in sync — at the cost of a network round-trip. Cache the output and run the generator infrequently.

Q: Does the network call hit my GitHub rate limit?

The repository-page fetch is unauthenticated and counts against the regular github.com allowance, which is generous for browser-style traffic. The fixture pass calls https://api.github.com/markdown, an unauthenticated endpoint with a separate rate limit. If you regenerate constantly from the same IP, you can be throttled. The 1-day disk cache for CSS files and 7-day cache for the fixture make repeated runs cheap.

Q: Where does the disk cache live?

node_modules/.cache/generate-github-markdown-css/ relative to the working directory. CSS files cache for 1 day, the fixture caches for 7 days. Delete the directory to force a fresh fetch.

Q: Can I run this fully offline?

No. The tool requires a live HTTP connection to github.com and (unless you pass --no-use-fixture) api.github.com. There is no offline or "shipped snapshot" mode.

Q: How is this different from github-markdown-css (without the generate- prefix)?

github-markdown-css is the static published stylesheet — a snapshot somebody runs the generator against and publishes to npm. generate-github-markdown-css is the upstream tool that produces those snapshots. Use the static package if you want zero build steps; use this generator if you want to re-snapshot on your own cadence and pick non-default themes or scoping.

Q: How do I add my own theme?

You can't through this tool. The theme list is whatever GitHub itself exposes on its live page — adding entries upstream is a GitHub change, not a project change. To customize colours after generation, run with --only-style to get just the rules, then ship your own variables file with the values you want.

Q: Why is my output different on different runs?

Two reasons: GitHub may have shipped a CSS update (use the cache or pin the run time to dampen this), or the disk cache expired (re-fetched files can differ from the previous fetch). For reproducible builds in CI, vendor the generated CSS into your repository and refresh on a schedule.

Q: Can I use this in a browser bundle?

No. The package depends on node:fs, node:path, and Node-specific behaviours of fetch (no CORS), so it only works in a Node.js process. Run it at build time and ship the resulting .css to the browser.

Q: How do I preserve var() references in single-theme output?

Pass --preserve-variables (or preserveVariables: true). By default, single-theme mode inlines variable values for a smaller, easier-to-read output. With --preserve-variables, you get a leading variable block plus rules that reference it.

Q: Does it support GitHub's ==highlight== syntax (issue #36)?

Whatever GitHub renders, the generator captures. As of commit 58d00ca, GitHub does not support the ==highlight== syntax in the standard pipeline, so the output stylesheet has no rules for it.

Q: Does it style <dl> / <dt> / <dd> (issue #23)?

Yes — dl, dt, and dd are in the allow-list (see constants.js ALLOW_TAGS), so any rules GitHub ships for them flow into the output.

Q: Does it style task lists / checkboxes?

Yes. The classes .contains-task-list, .task-list-item, and .task-list-item-checkbox are in ALLOW_CLASS, and <input> is in ALLOW_TAGS, so GitHub-style task lists render correctly.

Q: Does it style alert blocks (NOTE / TIP / WARNING / IMPORTANT / CAUTION)?

Yes. The full set of .markdown-alert* classes plus the .octicon-info / .octicon-light-bulb / .octicon-report / .octicon-alert / .octicon-stop icons are in ALLOW_CLASS. Make sure your Markdown renderer emits the correct alert HTML structure (matching GitHub's).

Q: Where do I report bugs?

github.com/sindresorhus/generate-github-markdown-css/issues. Include the version, the command you ran, the cached files (if relevant), and the resulting output.

Q: What's the license?

MIT. See the license file in the repository.