Theming & Dark Mode

6 min readUpdated September 19, 2026

Every block this plugin renders, the code block and all eleven API-documentation blocks, shares one theming system scoped to the .nahnu-code-block class. There are three ways to integrate, and you can combine any or all of them:

Your theme or plugin already sets a class or attribute for dark mode (for example <body class="dark-mode"> or <html data-theme="dark">). Use the PHP selector filters below. No JavaScript required, and it updates live the instant your class or attribute changes, since it works through real CSS.
Your dark-mode toggle is driven by JavaScript and you want to tell Nahnu Code Block directly when it fires. Use the JS API below.
You want to rebrand the actual colors, light and/or dark, to match a site’s palette. Use the nahnu_code_block_theme_variables filter, or, if you’d rather not write code, the built-in Settings page.

This is aimed at developers and site builders customizing how the plugin looks. If you just want to know what settings exist in the block editor itself, each block’s own doc covers that.

Settings page#

For rebranding colors without writing a filter, Settings → Nahnu Code Block has a color picker for each of the seven core variables, accent, text on accent, background, header/footer background, text, muted text, and border, in both light and dark mode. Every field defaults to (and can be reset to) the plugin’s own built-in palette by clearing it.

This is just an admin UI in front of the same nahnu_code_block_theme_variables filter covered below. Saved colors are applied at priority 5, so they act as your site’s new defaults while a developer’s own filter, at the normal default priority 10, can still override them further if both are in play. Every block picks this up automatically regardless of how it was placed on the page: the block editor, nahnu_code_block_render() / nahnu_code_block_the() from a template, or the shortcode.

Per-instance branding overrides#

Sometimes one specific block needs its own colors rather than the site-wide palette, a single partner-branded endpoint, for example. There are two ways to do that, both accepting the same seven variable names.

From the shortcode, using plain attributes:

Shortcode color override

[nahnu_code_block block="endpoint" method="POST" path="/v1/users" accentColor="#ff5500" accentTextColor="#ffffff"]

Supported attributes: accentColor, accentTextColor, bgColor, chromeBgColor, textColor, borderColor, mutedColor. Each accepts a hex color, rgb() / rgba(), hsl() / hsla(), a CSS color keyword, or var(--your-own-css-variable) to defer to your theme’s own design token instead of a literal color.

From PHP, via the third argument to nahnu_code_block_render() / nahnu_code_block_the() (see the doc on building your own importer), using the raw CSS variable names directly:

PHP color override

echo nahnu_code_block_render( 'endpoint', array( 'method' => 'POST', 'path' => '/v1/users' ), array(
    '--nahnu-code-block-accent'    => '#ff5500',
    '--nahnu-code-block-accent-fg' => '#ffffff',
) );

Either way, the override is scoped to just that rendered instance, via an inline-styled wrapper <div> using CSS custom properties. It never changes what any other block on the page, or the Settings page’s own saved values, look like. Anything that isn’t a real color value, or isn’t one of the seven recognized variable names, is silently dropped rather than printed, so this is safe to wire up to user-supplied input.

PHP filters#

`nahnu_code_block_dark_mode_selectors`#

An array of CSS selectors. If any of them matches an element on the page, typically <html> or <body>, every Nahnu Code Block on the page switches to dark. This is checked via real CSS descendant selectors, so there’s no JavaScript and no timing issues, and it reacts instantly to class changes.

Add a dark-mode selector

add_filter( 'nahnu_code_block_dark_mode_selectors', function ( $selectors ) {
    $selectors[] = 'body.my-theme-dark-mode';
    return $selectors;
} );

Defaults: html[data-theme="dark"], body.dark-mode, body.dark-theme.

Built in, automatic, no setup needed: if WP Super Docs is active, its html[data-wpsd-theme="dark"/"light"] attribute is already registered for you, and its actual color palette, accent, text, background, border, muted, sidebar, including any custom colors configured in its own Appearance settings, is mapped onto Nahnu Code Block’s variables via CSS var() fallback. That’s why a code block matches the surrounding docs theme automatically with no configuration on your part.

`nahnu_code_block_light_mode_selectors`#

The same idea in reverse: selectors that force light mode even if the OS preference or a dark selector above would otherwise apply dark. Empty by default.

Add a light-mode selector

add_filter( 'nahnu_code_block_light_mode_selectors', function ( $selectors ) {
    $selectors[] = 'html[data-theme="light"]';
    return $selectors;
} );

`nahnu_code_block_theme_variables`#

Override the actual CSS custom property values for a mode. Runs for both 'light' and 'dark', check the $mode argument to tell which. You only need to return the keys you want to change; anything you omit keeps its default.

Override a theme color

add_filter( 'nahnu_code_block_theme_variables', function ( $vars, $mode ) {
    if ( 'dark' === $mode ) {
        $vars['--nahnu-code-block-accent'] = '#ff5c8a'; // match brand color
    }
    return $vars;
}, 10, 2 );

Available variable names: --nahnu-code-block-bg, -chrome-bg, -fg, -border, -muted, -accent, -accent-fg, and the syntax-highlighting token colors -token-comment, -token-punctuation, -token-property, -token-string, -token-operator, -token-keyword, -token-function, -token-variable.

JavaScript API#

window.NahnuCodeBlock is available on any page where a Nahnu Code Block asset has loaded.

`NahnuCodeBlock.setTheme( theme, options )`#

theme: 'dark', 'light', or 'auto' (clears the override and lets the CSS cascade, OS preference or your selectors, decide again).
options.scope: optional. Pass a specific .nahnu-code-block element to affect only that instance; omit it to affect every block on the page.

Call this from your own dark-mode toggle’s click handler:

Wire up a theme toggle

myThemeToggleButton.addEventListener( 'click', function () {
    var isDark = document.body.classList.toggle( 'my-theme-dark-mode' );
    window.NahnuCodeBlock.setTheme( isDark ? 'dark' : 'light' );
} );

If body.my-theme-dark-mode is already registered via the PHP selector filter above, this call is actually optional, the CSS will already have switched. Call it anyway if you want the change to apply instantly without waiting on a style recalculation, or if you’re toggling something the CSS selector filter can’t see.

`NahnuCodeBlock.getTheme( blockEl )`#

Returns 'dark' or 'light' for a given block element (or the first one on the page if you omit the argument). Checks, in order: an explicit manual override, then your registered selectors, then OS preference. This is advisory, best-effort for reading state in JS. The actual visual result is always determined by CSS.

`nahnuCodeBlock:themechange` event#

Dispatched on document every time setTheme() runs, including from the plugin’s own per-block toggle button, with event.detail = { theme, scope }. Listen for this if some other widget on your page needs to stay in sync with a Nahnu Code Block’s theme.

Listen for theme changes

document.addEventListener( 'nahnuCodeBlock:themechange', function ( event ) {
    console.log( 'Nahnu Code Block switched to', event.detail.theme );
} );

Tips#

If you’re documenting on top of WP Super Docs, check before adding your own dark-mode selector or theme-variables filter. The plugin already auto-detects WP Super Docs’ theme attribute and colors, so a manual filter on top of that is usually redundant and can fight with it.
Prefer the CSS selector filters over the JS API when you can. They need no JavaScript, have no timing issues, and keep working even if a script on the page fails to load. Reach for setTheme() only when your toggle genuinely can’t be expressed as a CSS selector, or when you want the switch to feel instant without waiting on a style recalculation.
Test color overrides in both modes. A nahnu_code_block_theme_variables filter that only branches on 'dark' will leave light mode using plugin defaults, which is sometimes what you want and sometimes a gap you didn’t mean to leave.
Use var(--your-own-css-variable) in a per-instance override (shortcode or PHP) instead of a literal color when the value should track your theme’s own design token rather than being pinned to one hex value forever.
Remember per-instance overrides win over everything else, including the Settings page. If a single block looks wrong after a site-wide color change, check its own shortcode attributes or the third argument of its nahnu_code_block_render() call before assuming the filter isn’t working.

Theming & Dark Mode

Settings page#

Per-instance branding overrides#

PHP filters#

nahnu_code_block_dark_mode_selectors#

nahnu_code_block_light_mode_selectors#

nahnu_code_block_theme_variables#