# 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:

```bash
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.

```html
<!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

```bash
npx generate-github-markdown-css --list
```

```text
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:

```bash
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:

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

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

```bash
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:

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

Then import and call it from any ES module:

```js
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)

```bash
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

| Method | Verification command | Expected output |
|---|---|---|
| `npx` | `npx generate-github-markdown-css --help` | Usage block listing all flags |
| Global | `github-markdown-css --list` | Six theme names, one per line |
| Library | `node -e "import('generate-github-markdown-css').then(m => m.default({list:true})).then(console.log)"` | Six theme names |

> [!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)

| Flag | Type | Default | Effect |
|---|---|---|---|
| `--list` | boolean | `false` | Print the available theme names (one per line) and exit. |
| `--light <theme>` | string | `light` | Theme used in the light slot. |
| `--dark <theme>` | string | `dark` | Theme used in the dark slot. |
| `--theme <name>` | string | (none) | Single-theme shortcut. Accepts `auto` or any name from `--list`. Aliased as `--type`. |
| `--preserve-variables` | boolean | `false` | Keep `var(--name)` references in the output instead of inlining their values. |
| `--only-style` | boolean | `false` | Emit only the rule definitions (no variable blocks). Forces `--preserve-variables`. |
| `--only-variables` | boolean | `false` | Emit only the variable blocks (no rule definitions). Forces `--preserve-variables`. |
| `--no-use-fixture` | boolean | inverse of `useFixture` (default `true`) | Skip the GitHub Markdown API fixture pass. Output omits dynamically-generated classes. |
| `--root-selector <selector>` | string | `.markdown-body` | Replace `.markdown-body` everywhere in the output with the given selector. |
| `--transparent-background` | boolean | `false` | Replace the body background with `transparent`. |

### 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).

| Option | Type | Default | Effect |
|---|---|---|---|
| `light` | string | `'light'` | Theme used in the light slot. |
| `dark` | string | `'dark'` | Theme used in the dark slot. |
| `list` | boolean | `false` | Return the available theme names instead of CSS. |
| `preserveVariables` | boolean | `false` | Keep `var(--name)` references instead of inlining. |
| `onlyVariables` | boolean | `false` | Return only the variable blocks. Forces `preserveVariables`. |
| `onlyStyles` | boolean | `false` | Return only the rule definitions. Forces `preserveVariables`. |
| `useFixture` | boolean | `true` | Run the GitHub Markdown API fixture pass. |
| `rootSelector` | string | `'.markdown-body'` | Replace `.markdown-body` everywhere in the output with the given selector. |
| `transparentBackground` | boolean | `false` | Replace the body background with `transparent`. |

> [!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:

| Inputs | Mode | Output shape |
|---|---|---|
| `light` and `dark` differ | **auto** | Two `prefers-color-scheme` blocks; variables preserved by definition |
| `light === dark` | **single** | Flat stylesheet; variables inlined into each rule unless `preserveVariables` is set |
| `--theme=auto` (or omit `--theme`) | auto | Same as differing `light`/`dark` |
| `--theme=<name>` (other than `auto`) | single | Forces `light = dark = name` |

> [!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:

| Theme | Description |
|---|---|
| `light` | Default GitHub light theme. |
| `dark` | Default GitHub dark theme. |
| `dark_dimmed` | Lower-contrast dark theme. |
| `dark_high_contrast` | High-contrast dark theme for accessibility. |
| `dark_colorblind` | Dark theme with colorblind-friendly palette. |
| `light_colorblind` | Light theme with colorblind-friendly palette. |

> [!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)

```bash
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

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

```bash
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

```bash
github-markdown-css --list
```

```text
light
dark
dark_dimmed
dark_high_contrast
dark_colorblind
light_colorblind
```

### Calling from JavaScript

```js
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:

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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.

```js
// 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

```bash
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

```bash
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`:

```js
// 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`:

```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`):**

```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):**

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

**Jekyll (Rakefile or pre-build hook):**

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

In all three, your layout pulls in the stylesheet:

```html
<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:

```yaml
# .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:

```bash
# 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.

```html
<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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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`:

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

**Solution:**

```js
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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://github.com/sindresorhus/generate-github-markdown-css/issues/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](https://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.

---

_Generated April 2026 from sindresorhus/generate-github-markdown-css at 58d00ca. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._