Skip to main content

Confluence Dark Mode Apps FAQ: Themes, Fonts & Code Blocks

· 13 min read
NGPilot
NGPilot
NGPilot

Dark mode has moved from a developer preference to an expectation across every tool in the modern workspace. Confluence Cloud introduced a native dark mode toggle, which is a welcome step, but the reality of implementing a fully dark-themed Confluence experience is more nuanced than flipping a single switch.

The built-in dark mode transforms the Confluence chrome -- the navigation bar, sidebar, and page background -- but it does not reach inside macro content. Code blocks, diagrams, embedded content, and custom-styled elements often remain in their default light appearance, creating a jarring mismatch that breaks the immersive dark experience your team is looking for.

This FAQ addresses the most common questions teams have about achieving a cohesive dark mode setup in Confluence. We cover what the native dark mode handles, where it falls short, and how marketplace apps from NGPILOT and others fill the gaps for code blocks, Mermaid diagrams, typography, and overall page design.

Does Confluence have a built-in dark mode?​

Yes, Confluence Cloud ships with a native dark mode. You can activate it by clicking your profile avatar in the top-right corner and toggling the theme option between light and dark. Once enabled, Confluence applies a dark color scheme to the entire interface: the top navigation bar, the left sidebar, page backgrounds, comment sections, and standard content areas all switch to dark tones.

However, the native dark mode has clear boundaries. It controls the application shell and standard Confluence content rendering, but it does not extend to content rendered inside third-party macros or custom-styled elements. This means:

  • Code blocks rendered by the default Confluence code macro keep their light background regardless of your theme setting.
  • Diagrams from macros like Mermaid, PlantUML, or Draw.io remain in their original color scheme.
  • Custom-styled content using inline HTML or CSS does not automatically adapt to the dark theme.
  • Third-party macro content depends entirely on whether the app developer has implemented dark mode support.

For teams that primarily use standard Confluence features like text, tables, and images, the built-in dark mode covers most needs. For engineering teams that rely heavily on code blocks, architecture diagrams, and technical documentation, the gaps are immediately visible and disruptive. This is where marketplace apps with dedicated dark theme support become essential.

Do NGPILOT apps support dark mode in Confluence?​

Yes, several NGPILOT apps are built with dual-theme support from the ground up. Rather than relying on Confluence to invert colors automatically, these apps ship their own dark and light theme configurations that you control independently. This approach gives you precise control over how content looks in each mode.

Modern Code Blocks for Confluence provides separate dark and light syntax highlighting themes. The dark theme uses a carefully tuned color palette inspired by popular IDE dark modes, with high-contrast syntax colors that remain readable against the dark background. You select the theme directly in the macro configuration, so code blocks always match your preferred look regardless of the Confluence-level theme setting.

Mermaid Plus for Confluence supports custom color themes that you can configure to work with both light and dark Confluence modes. You can set the theme per diagram using the configuration panel, choosing from Default, Dark, Forest, or Neutral themes. The macro also automatically adapts to Confluence's dark/light mode, adjusting text and background colors for readability.

Google Fonts for Confluence renders correctly in both light and dark modes because it focuses on font selection and typography rather than color. The fonts themselves are color-neutral -- they inherit the text color from the surrounding Confluence theme. This means your custom typography choices work seamlessly whether your team uses light mode, dark mode, or a mix of both.

The key principle across all these apps is that dark mode support is implemented at the content level, not left to chance with automatic color inversion. This produces results that look professional and intentional rather than washed out or poorly contrasted.

How do I get dark-themed code blocks in Confluence?​

Getting dark-themed code blocks in Confluence requires a marketplace app because the default Confluence code macro does not offer theme options. The default macro renders code against a light gray background with basic syntax coloring, and this appearance does not change when you enable Confluence's native dark mode.

Modern Code Blocks for Confluence solves this with a dedicated dark theme. Here is how to set it up:

  1. Install the app from the Atlassian Marketplace. It is available for Confluence Cloud.
  2. Insert the macro on any page by typing /modern-code-blocks in the editor or selecting it from the macro browser.
  3. Paste your code into the macro body and select the programming language for accurate syntax highlighting.
  4. Choose the dark theme in the macro configuration panel. The dark theme uses VS Code-style dark colors with high contrast for keywords, strings, comments, and other syntax elements.
  5. Save and publish the page to see the dark-themed code block in action.

The dark theme in Modern Code Blocks is designed to match the visual expectations developers have from their daily IDE work. Keywords appear in bright, distinguishable colors against the dark background. Strings, comments, and function names each have their own distinct color, making the code easy to scan and understand. Line numbers are rendered in a muted tone that is visible but does not compete with the code itself.

For teams that want consistency, you can configure the default theme at the app level so that every new code block starts with the dark theme pre-selected. Individual authors can still override this on a per-macro basis if a specific page calls for the light theme.

The app also supports features that enhance the dark code block experience: line highlighting for drawing attention to specific lines, collapsible sections for long code files, and a copy-to-clipboard button that is styled to match the dark theme. These features work together to create code blocks that feel like a native part of a dark-themed documentation experience rather than a jarring light-colored island on an otherwise dark page.

Can Mermaid diagrams use dark themes in Confluence?​

Yes, Mermaid diagrams can use dark themes in Confluence when you use an app that supports theme customization. The default Mermaid rendering in Confluence uses the standard light Mermaid theme, which produces diagrams with white or light gray backgrounds, dark text, and default blue color schemes. These diagrams stand out awkwardly against a dark Confluence page.

Mermaid Plus for Confluence provides full theme control for Mermaid diagrams:

  • Per-diagram theme selection: Choose from Default, Dark, Forest, or Neutral themes in the macro configuration panel for each diagram.
  • Custom color definitions: Use Mermaid's style and classDef statements to specify exact colors for nodes, edges, and labels that are optimized for dark backgrounds.

When building Mermaid diagrams for dark mode, keep these guidelines in mind:

  • Use light text colors for labels and node text. Dark text on a dark background is unreadable regardless of the diagram shape.
  • Choose saturated fill colors for nodes rather than pastel tones, which can appear washed out against dark backgrounds.
  • Increase stroke width on edges and node borders to maintain visual clarity at smaller sizes.
  • Test with actual dark mode enabled in Confluence to see how your diagram interacts with the surrounding page theme.

Mermaid Plus renders diagrams as SVG, which scales cleanly and respects color values precisely. This means the colors you specify are the colors that appear in the final output, without unexpected shifts or compression artifacts that can affect raster image formats.

Why do my custom fonts look different in dark mode?​

Font rendering is influenced by the background color in ways that many people do not anticipate. The same font at the same size can appear noticeably different when displayed against a dark background compared to a light one. This is caused by several factors:

Anti-aliasing behavior. Font rendering engines use sub-pixel anti-aliasing to make text look smooth on screen. The algorithms that drive this rely on the background color to determine how to blend the edges of each glyph. When the background changes from light to dark, the anti-aliasing produces different edge smoothing, which can make fonts appear slightly thinner or thicker.

Contrast perception. Human eyes perceive contrast differently depending on the surrounding brightness. Dark text on a light background and light text on a dark background at the same measured contrast ratio can look like different levels of contrast to the reader. Fonts that appear crisp and readable in light mode can seem slightly fuzzy or heavy in dark mode.

Font weight perception. Light text on a dark background tends to appear slightly bolder than dark text on a light background at the same font weight. This is a well-documented optical illusion in typography. Some designers recommend using a slightly lighter font weight for dark mode to compensate.

Google Fonts for Confluence handles these issues well because it uses web fonts loaded from the Google Fonts CDN, which are designed and hinted for screen rendering across various backgrounds. The app applies fonts through standard CSS mechanisms, so the text color inherits from Confluence's theme automatically. When Confluence switches to dark mode, the text color changes to a light shade and the font renders with appropriate anti-aliasing for the dark background.

To get the best results:

  • Choose fonts with good screen rendering. Fonts like Inter, Roboto, Source Sans Pro, and JetBrains Mono are specifically designed for screen legibility and perform well in both light and dark contexts.
  • Test at your actual usage sizes. A font that looks great at 16px in light mode might need adjustment at that size in dark mode. Test at the sizes you actually use in your documentation.
  • Avoid very thin font weights in dark mode. Weights below 300 often lose legibility against dark backgrounds, especially at smaller sizes.
  • Check heading and body text separately. Headings often use heavier weights that are less affected by the background change, while body text at regular weights shows more difference.

How do I make my Confluence pages look good in both light and dark mode?​

Building Confluence pages that work well in both light and dark modes requires a shift in how you think about content design. The goal is not to make the page look identical in both modes -- that is neither possible nor desirable. Instead, aim for pages that look intentional and polished in each mode on its own terms.

Use apps with dual-theme support. This is the single most impactful step. When your code blocks, diagrams, and typography each handle their own theme rendering, you avoid the patchwork appearance of some content adapting and other content staying light. Modern Code Blocks, Mermaid Plus, and Google Fonts all support both themes natively.

Avoid hardcoded colors in content. Confluence pages sometimes use inline styles or HTML macros with specific color values like color: #333 or background: #f5f5f5. These colors look correct in light mode but break in dark mode because the dark text on a dark background becomes invisible, or the light background clashes with the dark page. Use Confluence's built-in text formatting whenever possible, and let the theme control the colors.

Test every page in both modes. Make it part of your review process to check pages in both light and dark mode. What looks clean in one mode might have readability issues in the other. Pay special attention to:

  • Tables with colored header rows
  • Info panels and callout macros
  • Images with transparent backgrounds
  • Embedded content from external services
  • Custom HTML or CSS in macros

Use neutral or adaptive color palettes for diagrams. When creating Mermaid diagrams, choose colors that have sufficient contrast against both light and dark backgrounds. Mid-tone blues, teals, and greens often work well in both contexts. Avoid very light colors that disappear on light backgrounds or very dark colors that vanish on dark backgrounds.

Set sensible defaults at the app level. Configure your apps with theme defaults that match your team's most common mode. If 80% of your team uses dark mode, set Modern Code Blocks to default to the dark theme and Mermaid Plus to default to your dark color scheme. Team members who prefer light mode can override per-page if needed.

NGPILOT Apps Dark Mode Support​

AppDark Mode SupportDetails
Modern Code Blocks for ConfluenceFullDark and light syntax highlighting themes, configurable per macro and globally
Mermaid Plus for ConfluenceFullCustom color themes, per-diagram theme configuration, automatic dark/light adaptation, SVG rendering
Google Fonts for ConfluenceCompatibleFonts inherit theme colors automatically, no manual adjustment needed

Tips for Confluence Dark Mode​

Start with the built-in toggle. Before investing in marketplace apps, enable Confluence's native dark mode and assess where the gaps are for your team. Different teams have different content patterns, and understanding your specific needs helps you choose the right apps.

Standardize on one theme for your team. While Confluence allows each user to choose their own theme, teams that standardize on one mode can optimize their content more aggressively. If your team has standardized on dark mode, you can configure all your apps for dark-first rendering without worrying about light mode edge cases.

Create a style guide for dark mode. Document which colors, fonts, and diagram styles your team should use. Include examples of correctly formatted code blocks, diagrams, and pages in both light and dark modes. This reduces the trial-and-error for content authors and keeps your documentation visually consistent.

Review third-party app compatibility before installing. Not all Confluence apps handle dark mode well. Before installing a new app, test it with dark mode enabled to see how its macros render. Apps that only support light rendering will create visible inconsistencies on your dark-themed pages.

Use browser extensions for preview. Browser extensions that force dark mode on web pages can give you a preview of how your content might look, but they often produce poor results with Confluence because they apply blanket color inversion. Use them only for rough previews, not for final design decisions.

Keep accessibility in mind. Dark mode is not just an aesthetic preference. For some users, it is an accessibility requirement. Ensure that your dark-themed content meets WCAG contrast standards. Both Modern Code Blocks and Mermaid Plus use color palettes designed to maintain accessible contrast ratios in their dark themes.