Skip to Content
rehype-code-group

Troubleshooting

What to check when the ::: lines show on the page, tabs don't switch, or a choice isn't remembered.

I see ::: lines on the page

The plugin leaves a group as plain Markdown when it can't read it. Work through these in order.

  1. Is the plugin running? It is a rehype plugin, so it must be registered with your rehype or MDX plugins, not with the remark ones.
  2. Is it running at the right point? It looks for paragraphs and HTML elements. If another plugin turns code blocks into MDX components first, the group seems to have no panels, and you'll get Code group has 2 labels but 0 panels. Fumadocs' Shiki plugin is one example. Register rehype-code-group before such plugins. Highlighters that produce ordinary HTML elements can run in either order.
  3. Do the labels and panels match? In compact groups, every block between the markers is a panel. A stray paragraph adds one. Look for the panel-count message from the diagnostics.
  4. Is each marker its own paragraph? Leave blank lines around ::: code-group …, :::, and in rich groups :::: code-group, ::: code-tab … and ::::.
  5. Using [label] on fences? The remark companion must be installed, run before remark-rehype, and every fence in the group needs a label. Otherwise the group is left as it is, without a message.
  6. Is it a rich group? Malformed rich groups don't report anything. Check that each code-tab has a label, that only blank lines sit between tabs, and that the group ends with ::::.
  7. Is there a ] in a label? Labels in labels=[…] can't contain ].

Set diagnostics: "error" in CI so the problems that can be detected fail the build instead of shipping.

The tabs are there, but clicking does nothing

The markup is right but the client isn't running.

  • With assets: "none", check that your app imports rehype-code-group/client, and that the import runs in the browser. In Next.js, that means a client component ("use client").
  • With inline assets in a React app, the script is rendered by React and won't run on client-side navigation. Switch to assets: "none". See Asset delivery.
  • With external assets, check the browser's network panel for the scriptSrc URL, and the console for CSP errors.
  • Inside a shadow root, call initCodeGroups(shadowRoot).

Every panel is visible at once

That is the state before the client runs. Groups hide inactive panels only after the client adds data-rcg-enhanced. If it stays this way, see the previous section. If the client runs but panels are still visible, check that the stylesheet is loaded, or that your own CSS hides .rcg-block inside [data-rcg-enhanced].

The choice isn't remembered

  • persist needs a sync key. persist="local" alone does nothing.
  • Only local and url are valid values.
  • Values are matched by tab value. If the value changes, for example because it defaults to a label you've reworded, old saved choices no longer match. Set explicit values.
  • Some private browsing modes block local storage. The client carries on without saving.

Groups don't sync

  • Only rich groups can have a sync key. Groups generated by the package-manager plugin are compact.
  • Both groups need the same key, and tabs that should match need the same value.

My styles or colors don't apply

From the release after 2.0.0, any rule you write beats the bundled look, and the --rcg-* properties work on the group or any ancestor. See Overriding the bundled styles.

On 2.0.0 and earlier with the default inline assets, the plugin's <style> comes after your stylesheet and wins ties. Use a more specific selector, such as body .rehype-code-group, and set the properties on the group rather than :root.

Dark mode colors are wrong

The default colors follow the page's color-scheme. If your theme switch only toggles a class, set the custom properties under that class.

Duplicate IDs

IDs are numbered per transformed file, starting at rcg-0. If you combine several separately rendered fragments on one page, give each a different idPrefix. Otherwise two tabs can share an ID, and aria-controls points at the wrong panel.

MDX errors near a group

In MDX, { starts a JavaScript expression and < starts a JSX tag, even inside a label. Escape them, for example \{, or move the text into a code fence.

Edit on GitHub