Configuration

Sphinx configuration options for customizing sphinx-tabs behavior, builder compatibility, and asset loading.

Capabilities

Builder Compatibility Configuration

Specify additional Sphinx builders that should be considered compatible with sphinx-tabs.

sphinx_tabs_valid_builders = []

Type: List of strings
Default: [] (empty list)
Context: Extensions configuration

Usage:

# conf.py
sphinx_tabs_valid_builders = ['linkcheck', 'custom_builder']

Built-in Compatible Builders: The extension automatically supports these builders:

• html
• singlehtml
• dirhtml
• readthedocs
• readthedocsdirhtml
• readthedocssinglehtml
• readthedocssinglehtmllocalmedia
• spelling

Purpose:

• Extends compatibility beyond default HTML builders
• Enables tab functionality in custom or specialized builders
• Maintains backward compatibility with existing configurations

CSS Loading Control

Control whether the extension automatically loads its default CSS stylesheet.

sphinx_tabs_disable_css_loading = False

Type: Boolean
Default: False
Context: HTML builder configuration

Usage:

# conf.py - Disable default CSS to use custom styling
sphinx_tabs_disable_css_loading = True

When to Use:

• Custom theming requires different tab styles
• Integration with existing CSS frameworks
• Performance optimization with bundled assets
• Complete visual customization needed

Note: When disabled, you must provide your own CSS for tab functionality and styling.

Tab Closing Behavior

Control whether users can close tabs by clicking on the active tab.

sphinx_tabs_disable_tab_closing = False

Type: Boolean
Default: False
Context: HTML builder configuration

Usage:

# conf.py - Disable tab closing functionality
sphinx_tabs_disable_tab_closing = True

Behavior:

• False (default): Clicking active tab closes it, showing only tab labels
• True: Clicking active tab has no effect, content always visible

Use Cases:

• Always-visible content requirements
• Simplified user interaction
• Accessibility considerations
• Mobile-optimized layouts

Extension Registration

The configuration values are registered during extension setup.

def setup(app):
    """Register configuration values with Sphinx application"""
    app.add_config_value("sphinx_tabs_valid_builders", [], "")
    app.add_config_value("sphinx_tabs_disable_css_loading", False, "html", [bool])
    app.add_config_value("sphinx_tabs_disable_tab_closing", False, "html", [bool])

Configuration Value Registration:

• First parameter: Configuration name
• Second parameter: Default value
• Third parameter: Builder context ("" = all, "html" = HTML only)
• Fourth parameter: Type constraints (for validation)

Asset Management

Configuration affects how CSS and JavaScript assets are handled.

def update_context(app, pagename, templatename, context, doctree):
    """Conditionally add CSS/JS assets based on configuration and usage"""
    # Respects sphinx_tabs_disable_css_loading setting
    # Only loads assets on pages that actually use tabs

Asset Loading Logic:

1. Check if page contains tab directives
2. Respect sphinx_tabs_disable_css_loading setting
3. Add CSS file only if loading enabled
4. Always add JavaScript (required for functionality)
5. Handle Sphinx asset policy (always vs conditional)

Complete Configuration Example

# conf.py - Complete sphinx-tabs configuration
extensions = ['sphinx_tabs.tabs']

# Extend builder compatibility
sphinx_tabs_valid_builders = [
    'linkcheck',        # Allow tabs in link checking
    'epub',            # Enable for EPUB output
    'latex',           # Enable for LaTeX (limited functionality)
]

# Custom styling setup
sphinx_tabs_disable_css_loading = True  # Use custom CSS

# Always show tab content
sphinx_tabs_disable_tab_closing = True

# Custom CSS can be added via standard Sphinx methods
def setup(app):
    app.add_css_file('custom_tabs.css')

Troubleshooting

Tabs not appearing in custom builder:

• Add builder name to sphinx_tabs_valid_builders
• Verify builder generates HTML-compatible output

Styling issues:

• Check if sphinx_tabs_disable_css_loading = True is set
• Ensure custom CSS provides necessary tab styles
• Verify CSS file paths and loading order

Tab closing not working:

• Check sphinx_tabs_disable_tab_closing setting
• Verify JavaScript is loading correctly
• Test in compatible browser with JavaScript enabled