Skip to content

Custom CSS Styling

The EPMware documentation sites use a custom CSS file (docs/assets/css/custom.css) to override and extend the Material theme's default styling. Changes to this file affect every page on the site.

Current Custom Styles

The custom.css file contains styling for:

  • EPMware brand colors — CSS variables for the blue/orange color scheme
  • Admonition styling — Custom border and background colors for note and warning boxes
  • Procedure steps — Extra spacing between numbered list items
  • Image captions — Centered italic text below images
  • Status legends — Inline display for status indicator icons
  • Field reference tables — Colored headers for data reference tables
  • Sidebar scrollbar — Hidden scrollbar to prevent visual flash
  • Print styles — Page break and layout rules for printing
  • Mobile responsive — Smaller fonts and tighter padding on small screens
  • Code copy button — Blue/orange color scheme matching the brand
  • Search highlighting — Orange highlight for search result matches

EPMware Brand Colors

The brand colors are defined as CSS variables at the top of the file:

:root {
  --epmware-blue: #1976d2;
  --epmware-orange: #ff9800;
  --epmware-light-blue: #e3f2fd;
  --epmware-dark-blue: #0d47a1;
}

These variables are referenced throughout the CSS. If the brand colors change, update them here and all dependent styles will update automatically.

Making CSS Changes

Adding a New Style Rule

  1. Open docs/assets/css/custom.css.
  2. Add your new rule at the end of the file, or in the relevant section if one exists.
  3. Use a comment to describe what the rule does:
/* Custom styling for deployment status indicators */
.deployment-status {
  display: inline-block;
  padding: 0.2rem 0.6rem;
  border-radius: 0.2rem;
  font-size: 0.85rem;
}
  1. Run mkdocs serve and verify the change in your browser.

Scoping CSS Rules

To avoid unintended side effects, scope your CSS selectors as narrowly as possible:

/* GOOD — scoped to a specific context */
.field-reference th {
  background-color: var(--epmware-light-blue);
}

/* RISKY — affects ALL th elements site-wide */
th {
  background-color: var(--epmware-light-blue);
}

Use the .md-typeset prefix when targeting content within the main content area, which is how the Material theme namespaces its styles:

.md-typeset .custom-class {
  /* Only affects elements inside the main content area */
}

Test in Both Light and Dark Mode

The site supports light and dark mode via the toggle in the header. Any CSS changes should be tested in both modes. Hard-coded colors that look fine in light mode may become invisible or unreadable in dark mode. Prefer using the Material theme's built-in CSS variables (like --md-default-fg-color and --md-code-bg-color) which automatically adapt to the active color scheme.

Common CSS Patterns in Use

Image Captions

.md-typeset figure figcaption,
.md-typeset img + em {
  font-style: italic;
  color: var(--md-default-fg-color--light);
  font-size: 0.85rem;
  margin-top: 0.5rem;
  display: block;
  text-align: center;
}

This rule styles any <em> element that immediately follows an <img> element as a centered caption. This is why the markdown pattern ![alt](image.png)<br/>\n*caption* produces a properly styled caption.

@media print {
  .md-header, .md-sidebar, .md-footer {
    display: none !important;
  }
  h1 {
    page-break-before: always;
  }
}

Print styles hide navigation elements and force page breaks at major headings. Test print output by using your browser's Print Preview (Ctrl+P / Cmd+P).

CSS File Location

The CSS file is referenced in mkdocs.yml:

extra_css:
  - assets/css/custom.css

If you rename or move the CSS file, update this path in mkdocs.yml. The path is relative to the docs/ directory.