0
# Configuration
1

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

4
## Capabilities
5

6
### Builder Compatibility Configuration
7

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

10
```python { .api }
11
sphinx_tabs_valid_builders = []
12
```
13

14
**Type:** List of strings  
15
**Default:** `[]` (empty list)  
16
**Context:** Extensions configuration
17

18
**Usage:**
19
```python
20
# conf.py
21
sphinx_tabs_valid_builders = ['linkcheck', 'custom_builder']
22
```
23

24
**Built-in Compatible Builders:**
25
The extension automatically supports these builders:
26
- `html`
27
- `singlehtml` 
28
- `dirhtml`
29
- `readthedocs`
30
- `readthedocsdirhtml`
31
- `readthedocssinglehtml`
32
- `readthedocssinglehtmllocalmedia`
33
- `spelling`
34

35
**Purpose:**
36
- Extends compatibility beyond default HTML builders
37
- Enables tab functionality in custom or specialized builders
38
- Maintains backward compatibility with existing configurations
39

40
### CSS Loading Control
41

42
Control whether the extension automatically loads its default CSS stylesheet.
43

44
```python { .api }
45
sphinx_tabs_disable_css_loading = False
46
```
47

48
**Type:** Boolean  
49
**Default:** `False`  
50
**Context:** HTML builder configuration
51

52
**Usage:**
53
```python
54
# conf.py - Disable default CSS to use custom styling
55
sphinx_tabs_disable_css_loading = True
56
```
57

58
**When to Use:**
59
- Custom theming requires different tab styles
60
- Integration with existing CSS frameworks
61
- Performance optimization with bundled assets
62
- Complete visual customization needed
63

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

66
### Tab Closing Behavior
67

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

70
```python { .api }
71
sphinx_tabs_disable_tab_closing = False
72
```
73

74
**Type:** Boolean  
75
**Default:** `False`  
76
**Context:** HTML builder configuration
77

78
**Usage:**
79
```python
80
# conf.py - Disable tab closing functionality
81
sphinx_tabs_disable_tab_closing = True
82
```
83

84
**Behavior:**
85
- **False (default)**: Clicking active tab closes it, showing only tab labels
86
- **True**: Clicking active tab has no effect, content always visible
87

88
**Use Cases:**
89
- Always-visible content requirements
90
- Simplified user interaction
91
- Accessibility considerations
92
- Mobile-optimized layouts
93

94
## Extension Registration
95

96
The configuration values are registered during extension setup.
97

98
```python { .api }
99
def setup(app):
100
    """Register configuration values with Sphinx application"""
101
    app.add_config_value("sphinx_tabs_valid_builders", [], "")
102
    app.add_config_value("sphinx_tabs_disable_css_loading", False, "html", [bool])
103
    app.add_config_value("sphinx_tabs_disable_tab_closing", False, "html", [bool])
104
```
105

106
**Configuration Value Registration:**
107
- First parameter: Configuration name
108
- Second parameter: Default value
109
- Third parameter: Builder context ("" = all, "html" = HTML only)
110
- Fourth parameter: Type constraints (for validation)
111

112
## Asset Management
113

114
Configuration affects how CSS and JavaScript assets are handled.
115

116
```python { .api }
117
def update_context(app, pagename, templatename, context, doctree):
118
    """Conditionally add CSS/JS assets based on configuration and usage"""
119
    # Respects sphinx_tabs_disable_css_loading setting
120
    # Only loads assets on pages that actually use tabs
121
```
122

123
**Asset Loading Logic:**
124
1. Check if page contains tab directives
125
2. Respect `sphinx_tabs_disable_css_loading` setting
126
3. Add CSS file only if loading enabled
127
4. Always add JavaScript (required for functionality)
128
5. Handle Sphinx asset policy (`always` vs conditional)
129

130
## Complete Configuration Example
131

132
```python
133
# conf.py - Complete sphinx-tabs configuration
134
extensions = ['sphinx_tabs.tabs']
135

136
# Extend builder compatibility
137
sphinx_tabs_valid_builders = [
138
    'linkcheck',        # Allow tabs in link checking
139
    'epub',            # Enable for EPUB output
140
    'latex',           # Enable for LaTeX (limited functionality)
141
]
142

143
# Custom styling setup
144
sphinx_tabs_disable_css_loading = True  # Use custom CSS
145

146
# Always show tab content
147
sphinx_tabs_disable_tab_closing = True
148

149
# Custom CSS can be added via standard Sphinx methods
150
def setup(app):
151
    app.add_css_file('custom_tabs.css')
152
```
153

154
## Troubleshooting
155

156
**Tabs not appearing in custom builder:**
157
- Add builder name to `sphinx_tabs_valid_builders`
158
- Verify builder generates HTML-compatible output
159

160
**Styling issues:**
161
- Check if `sphinx_tabs_disable_css_loading = True` is set
162
- Ensure custom CSS provides necessary tab styles
163
- Verify CSS file paths and loading order
164

165
**Tab closing not working:**
166
- Check `sphinx_tabs_disable_tab_closing` setting
167
- Verify JavaScript is loading correctly
168
- Test in compatible browser with JavaScript enabled