Notebook CSS Class Consistency¶

This guide documents the consistent CSS class structure used for Jupyter notebooks in MkDocs, ensuring uniform styling and maintainable code.

Overview¶

The CSS class system follows Jupyter's standard jp-* naming convention, providing compatibility with existing Jupyter themes while allowing customization for MkDocs integration.

Class Structure¶

Container Classes¶

Main Container¶

.jupyter-notebook {
  /* Main notebook container */
  /* Applied by mkdocs-jupyter plugin */
}

Cell Containers¶

.jp-Cell {
  /* Base class for all cells */
}

.jp-CodeCell {
  /* Code cells with input/output */
}

.jp-MarkdownCell {
  /* Markdown text cells */
}

.jp-RawCell {
  /* Raw text cells */
}

Input/Output Areas¶

Input Areas¶

.jp-InputArea {
  /* Container for code input */
}

.jp-InputPrompt {
  /* Input prompt (In [1]:) */
}

.jp-InputArea-editor {
  /* Code editor container */
}

.jp-CodeMirrorEditor {
  /* CodeMirror editor styling */
}

Output Areas¶

.jp-OutputArea {
  /* Container for cell outputs */
}

.jp-OutputPrompt {
  /* Output prompt (Out[1]:) */
}

.jp-OutputArea-output {
  /* Output content container */
}

.jp-OutputArea-child {
  /* Individual output items */
}

Content Type Classes¶

Text Content¶

.jp-RenderedText {
  /* Plain text output */
  font-family: monospace;
}

.jp-RenderedHTMLCommon {
  /* HTML output */
  font-family: sans-serif;
}

.jp-RenderedMarkdown {
  /* Rendered markdown */
  line-height: 1.6;
}

Special Content¶

.jp-RenderedLatex {
  /* Mathematical equations */
  text-align: center;
}

.jp-RenderedImage {
  /* Images and plots */
  text-align: center;
}

.jupyter-widgets {
  /* Interactive widgets */
  padding: 0.5rem;
}

State Modifiers¶

Visibility Control¶

.jp-mod-hide-input {
  /* Hides input area */
}

.jp-mod-hide-output {
  /* Hides output area */
}

.jp-mod-hide {
  /* Hides entire cell */
}

.jp-mod-collapsed {
  /* Collapsed cell display */
}

Error States¶

.jp-OutputArea-error {
  /* Error output styling */
  background: rgba(255, 0, 0, 0.1);
}

.jp-OutputArea-stderr {
  /* Standard error stream */
  color: #d32f2f;
}

Usage Examples¶

Basic Code Cell Structure¶

<div class="jp-Cell jp-CodeCell">
  <div class="jp-InputArea">
    <div class="jp-InputPrompt">In [1]:</div>
    <div class="jp-InputArea-editor">
      <div class="jp-CodeMirrorEditor">
        <!-- Code content -->
      </div>
    </div>
  </div>
  <div class="jp-OutputArea">
    <div class="jp-OutputPrompt">Out[1]:</div>
    <div class="jp-OutputArea-output">
      <div class="jp-OutputArea-child">
        <div class="jp-RenderedText">
          <!-- Output content -->
        </div>
      </div>
    </div>
  </div>
</div>

Markdown Cell Structure¶

<div class="jp-Cell jp-MarkdownCell">
  <div class="jp-RenderedMarkdown">
    <!-- Rendered markdown content -->
  </div>
</div>

Styling Guidelines¶

Theme Integration¶

The CSS classes adapt to MkDocs Material theme colors:

/* Light theme */
[data-md-color-scheme="default"] .jupyter-notebook {
  background: rgba(0, 0, 0, 0.02);
  border: 1px solid rgba(0, 0, 0, 0.1);
}

/* Dark theme */
[data-md-color-scheme="slate"] .jupyter-notebook {
  background: rgba(255, 255, 255, 0.02);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

Responsive Design¶

Classes include responsive breakpoints:

Desktop (>76.25em): Full layout with side prompts
Tablet (45-76.25em): Compact prompts, reduced spacing
Mobile (<45em): Stacked layout, minimal prompts

Accessibility¶

All classes include accessibility features:

Focus indicators: Visible keyboard navigation
Screen reader support: Hidden prompt text
High contrast mode: Enhanced borders and colors
Reduced motion: Disabled transitions

Configuration¶

Plugin Configuration¶

In mkdocs.yml:

plugins:
  - mkdocs-jupyter:
      custom_css_class: jupyter-notebook
      theme: dark

CSS Loading¶

Add the stylesheet to mkdocs.yml:

extra_css:
  - assets/stylesheets/jupyter-notebooks.css

Customization¶

Utility Classes¶

Additional utility classes for customization:

/* Spacing utilities */
.jp-Cell--compact { margin: 0.25rem 0; }
.jp-Cell--spacious { margin: 1.5rem 0; }

/* Width utilities */
.jp-OutputArea--full-width { width: 100%; }
.jp-OutputArea--centered { margin: 0 auto; max-width: 80%; }

/* Text size utilities */
.jp-RenderedText--small { font-size: 0.75rem; }
.jp-RenderedText--large { font-size: 1rem; }

/* Highlighting utilities */
.jp-Cell--highlighted {
  background: rgba(var(--md-accent-fg-color), 0.1);
  border-left: 4px solid var(--md-accent-fg-color);
}

Custom Themes¶

Override default styles for custom themes:

/* Custom theme example */
.jupyter-notebook.theme-custom {
  --jp-input-bg: #f5f5f5;
  --jp-output-bg: #ffffff;
  --jp-prompt-color: #666666;
}

.jupyter-notebook.theme-custom .jp-InputArea {
  background: var(--jp-input-bg);
}

Best Practices¶

1. Use Semantic Classes¶

Prefer .jp-RenderedText over generic .text
Use modifier classes for states (.jp-mod-*)

2. Maintain Hierarchy¶

Keep cell structure consistent
Nest areas properly (input/output within cells)

3. Avoid Inline Styles¶

Use CSS classes for all styling
Keep specificity low for easy overrides

4. Test Responsiveness¶

Check all breakpoints
Ensure readability on mobile

5. Consider Accessibility¶

Test with screen readers
Verify keyboard navigation
Check contrast ratios

Migration Guide¶

From Default mkdocs-jupyter¶

If migrating from default styling:

Add the CSS file to your project
Update mkdocs.yml configuration
Test existing notebooks for compatibility
Adjust custom styles as needed

From Custom Styles¶

To migrate custom styles:

Map existing classes to jp-* equivalents
Update selectors in custom CSS
Test thoroughly across themes
Document any custom utilities

Examples¶

See these notebooks for live examples: - CSS Class Demo - Interactive demonstration - Output Examples - Various output types - Widget Examples - Interactive elements

Troubleshooting¶

Common Issues¶

Classes not applied: Check custom_css_class in plugin config
Styling conflicts: Increase specificity or use !important sparingly
Missing styles: Ensure CSS file is loaded in extra_css
Theme issues: Test both light and dark themes

Debug Tips¶

Use browser DevTools to: - Inspect applied classes - Check CSS load order - Test responsive breakpoints - Verify accessibility features