Extensions & Integrations

This page explores various Asciidoctor extensions and third-party integrations. Some work seamlessly with the dark theme, others may need additional styling. Toggle between light and dark modes to see how each renders.

Tabs Extension

The @asciidoctor/tabs extension creates tabbed content blocks—perfect for showing alternatives like package managers or platform-specific instructions.

JavaScript
const greeting = "Hello, dark mode!";
console.log(greeting);
Python
greeting = "Hello, dark mode!"
print(greeting)
Ruby
greeting = "Hello, dark mode!"
puts greeting
STEM / Mathematical Notation

AsciiDoc supports mathematical notation via MathJax or KaTeX. The formulas render as SVG or HTML, typically inheriting text color.

When latexmath is enabled, you can write inline math like \(\sqrt{x^2 + y^2}\) or display equations:

\[E = mc^2\]
\[\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}\]
Math rendering depends on your playbook’s STEM configuration. If formulas don’t appear, ensure asciidoc.attributes.stem is set.
Kroki Diagrams

Kroki renders diagrams from text—Mermaid, PlantUML, D2, and dozens more. These generate SVGs that may need dark-mode-aware colors.

Here’s a Mermaid flowchart (requires Kroki or native Mermaid integration):

graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
Diagram colors are defined in the diagram source, not CSS. For dark mode compatibility, use neutral colors or theme-aware palettes in your diagram definitions.
PlantUML Sequence

PlantUML excels at sequence diagrams, class diagrams, and more. The default colors are light-theme oriented.

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another request
Bob --> Alice: Another response
@enduml
PlantUML supports skinparam for theming. Use skinparam backgroundColor transparent and dark-friendly colors for better results.

Embedded Content

Iframes and embedded widgets maintain their own styling—they don’t inherit from the parent page’s CSS.

Video Embeds

YouTube, Vimeo, and other video embeds work fine—the player chrome adapts to the video, not your site theme.

Raw HTML Passthrough

Passthrough blocks let you inject arbitrary HTML. Inline styles override the theme, so plan accordingly.

Custom HTML Block
This has hardcoded colors—it looks the same in both themes.

Interactive Elements

Keyboard Shortcuts

The kbd macro renders keyboard shortcuts. These typically style well in dark mode.

Press Ctrl+Shift+P to open the command palette.

Use Cmd+K then Cmd+S to save all files.

Common shortcuts: Esc, Enter, Tab, Space

Menu & Button UI Macros

Menu selections and button references help document GUIs.

Select File  Save As…​  PDF to export.

Click OK to confirm or Cancel to abort.

Navigate to Settings  Appearance  Theme  Dark.

Font Icons

Font Awesome Icons

When :icons: font is set, AsciiDoc renders icons via Font Awesome. These inherit text color automatically.

Love this theme

Write some code

Light mode / Dark mode

Check out the repo

Warnings stand out

Custom Roles & Styling

Text Roles

Custom roles apply CSS classes. The dark theme styles common roles, but custom ones need your own CSS.

Lead paragraphs introduce sections with emphasis.

Small text for footnotes or asides.

Big text for impact.

Underlined for emphasis.

Struck through for deletions.

What Needs Extra Work?

Some extensions require additional dark mode CSS:

Extension Status Notes

Tabs (@asciidoctor/tabs)

Works

Inherits theme colors

STEM / Math

Works

SVG/HTML inherits text color

Kroki / Diagrams

Partial

Diagram colors are hardcoded in source

Video embeds

Works

Player has own chrome

HTML Passthrough

Manual

Inline styles override theme

Keyboard macros

Works

Styled by theme

Menu/Button macros

Works

Styled by theme

Font icons

Works

Inherits text color

Custom roles

Partial

Standard roles styled; custom need CSS

Extending for Your Content

To style custom elements in dark mode, add selectors to your CSS:

/* Your custom component */
html.dark-theme .my-custom-widget {
  background-color: #25262b;
  color: #c1c2c5;
  border-color: #373a40;
}

/* Dark-mode-aware diagram wrapper */
html.dark-theme .diagram-wrapper svg {
  filter: invert(0.85) hue-rotate(180deg);
}
The filter: invert() hue-rotate() trick can make light-themed diagrams readable in dark mode, though colors will shift.