Skip to content

MkDocs CSS Styles Documentation

This documentation describes the custom CSS styles available for MkDocs-rendered markdown files. These styles are loaded via the extra_css configuration in mkdocs.yml and provide enhanced formatting beyond standard markdown.

Available Stylesheets

The project uses four main custom CSS files:

  • common.css - Image modifiers, captions, tables, and Material for MkDocs customizations
  • iot.css - IoT-specific styles (breadboard images)
  • db.css - Database course specific styles (floating text)
  • slide.css - Full-screen slide/presentation mode
  • opsman.css - Custom admonitions (currently only pied-piper style)

Image Styling with URL Fragments

MkDocs allows you to style images by adding fragment identifiers (hash anchors) to the image URL. This is the most convenient way to apply CSS styles without writing HTML.

Figure Images

For standard figures with controlled dimensions:

1
![Diagram description](images/diagram.png#figure)

Result: Image with max-width of 80% and max-height of 20rem.

Stretch Images

For full-width images like banners:

1
![Banner](images/banner.png#stretch)

Result: Image stretches to 100% width of container.

Centred Images

For centred block images with margins:

1
![Architecture diagram](images/architecture.png#centred)

Result: Centred image with max-width 500px and 4em vertical margins.

Centred Short Images

For smaller centred images:

1
![Logo](images/logo.png#centred_short)

Result: Centred image with max-height 300px and 30px vertical margins.

Inline Centre Images

For small centred inline images:

1
![Icon diagram](images/icon-diagram.png#inline-center)

Result: Centred image with max-width 200px and 30px vertical margins.

For larger inline centred images, use #inline-center-large (max-width 400px).

Icon Images

For inline icons that align with text:

1
![Python icon](images/python.png#icon) Python documentation

Result: 24px height icon with vertical alignment at text-bottom.

With links: 

1
[![Arduino icon](images/arduino.png#icon) Arduino reference](https://www.arduino.cc/)

Icon Prefix

For icons that float to the left of a paragraph:

1
2
![Warning icon](images/warning.png#icon-prefix)
This is an important message that will wrap around the icon.

Result: 24px icon floated left with 0.5em top margin.

Icon Indented

For indented icon links in lists:

1
[![Tutorial icon](images/tutorial.png#icon-indented) Getting Started Tutorial](link)

Result: 24px icon with 5em left margin, suitable for nested content.

Slide Icon

For icons positioned at the right of content:

1
![Presentation](images/slides.png#slide)

Result: 24px icon floated right, aligned with text-bottom.

Left Leader Images

For images that lead a paragraph, floating left:

1
2
3
![Portrait](images/person.png#left-leader)

This text will wrap around the image on the right side...

Result: 200px height image floated left with 30px right margin.

Right Inset Images

For smaller images inset on the right:

1
2
3
![Diagram](images/small-diagram.png#right-inset)

The text flows around this smaller diagram...

Result: 160px height image floated right with 30px margins.

Breadboard Images (IoT-specific)

For circuit breadboard diagrams:

1
![Breadboard layout](images/circuit.png#breadboard)

Result: Centred block image with fixed width of 500px and 30px vertical margins.

Captions and Attributions

Image with Caption

Combine centred images with caption divs:

1
2
![System architecture](images/architecture.png#centred)
<div class="caption">Figure 1: The system architecture showing the main components and their relationships</div>

Features: - Centred block display with max-width 500px - Italic, small font - Automatic spacing with -4em top margin and 4em bottom margin

Caption Without Space

For captions that don't need special margin adjustments:

1
<div class="caption-no-space">Description of the content above</div>

Source Attribution

To add source information that automatically prepends "Source: ":

1
2
![Research diagram](images/research.png#centred)
<div class="attribution">Smith, J. (2023). Journal of Computer Science.</div>

Result: Displays as "Source: Smith, J. (2023). Journal of Computer Science." in italic, small font.

Table Customizations

Suppressing Table Headers

To create a table without visible headers (useful for layout):

1
2
3
4
5
6
---

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |
| Data 3   | Data 4   |

Note: The horizontal rule (---) immediately before the table triggers header suppression.

Equal Column Widths

For tables with forced equal column widths:

1
2
3
4
5
6
---
{: .two-equal-columns}

| Column 1 | Column 2 |
|----------|----------|
| Short    | Very long content that would normally make this column wider |

Result: Both columns forced to 50% width regardless of content.

Pretty Tables

For formatted tables with alternating row colors:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<table class="pretty">
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Feature 1</td>
      <td>Description 1</td>
    </tr>
    <tr>
      <td>Feature 2</td>
      <td>Description 2</td>
    </tr>
  </tbody>
</table>

Features: - Odd rows have light grey background (#f2f2f2) - Headers have blue background (#adf) with bold text - 5-10px cell padding

InfoTable (Legacy)

For tables with red branding:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<table class="infoTable">
  <thead>
    <tr>
      <th>Column 1</th>
      <th>Column 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Data 1</td>
      <td>Data 2</td>
    </tr>
  </tbody>
</table>

Features: - Red border (3px top, 1px sides) - White text on red background headers - Centred on page

Floating Text (Database-specific)

For text that floats to the right of content:

1
2
3
<div class="float-text">
This text will float to the right side with a width of 400px.
</div>

Custom Admonitions

Pied Piper Admonition (Operations Manual)

For special operations manual callouts:

1
2
3
4
!!! pied-piper "Title Here"
    Content of the admonition goes here.

    Can include multiple paragraphs.

Result: Green-bordered admonition with custom Pied Piper icon.

Slide/Presentation Mode

The slide.css stylesheet enables full-screen presentation mode. This is typically triggered via JavaScript and creates an overlay for displaying content as slides.

Slide Elements

Content can be marked for slide display:

1
2
3
4
5
<div class="slide-title-text">Introduction to MkDocs</div>

<div class="slide">
  <img src="icon.png" alt="Click for slide">
</div>

Features: - Full viewport overlay (100vw × 100vh) - Centred content with large font size (2.5vw) - Fixed title at top - Fade-in animation - Click anywhere to dismiss

Slide Content Styling

When content is displayed in slide mode: - Images scale to max 90% width and 80vh height - Tables, lists, and blockquotes are left-aligned - Code blocks use large font (2.5vw) - Tables get alternating row colors - Headers have steelblue background

Material for MkDocs Adjustments

The common.css includes several adjustments for Material for MkDocs theme:

Links in paragraphs and lists use a blue color (#448aff).

Blockquote Margins

Blockquotes have 40px margins for better spacing.

Table Cell Alignment

Table cells are vertically aligned to top by default.

Font Size Inheritance

Tables, admonitions, and details elements inherit font size from parent instead of being forced to specific sizes.

Navigation links allow superscript and subscript characters to display properly with left justification.

Material Symbols

Material Symbols Rounded icons are configured with: - FILL: 0 - Weight: 200 - GRAD: 0 - Size: 40

Index Page Utilities

Index Right Float

For floating content to the right on index pages:

1
2
3
<div class="index-right">
  <img src="images/video.mp4" alt="Demo">
</div>

Result: Content floated right with 4em left margin and -10em right margin (extends into margin area).

Practical Examples

Example 1: Article with Images and Captions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# IoT Tutorial: LED Control

In this tutorial, we'll learn how to control an LED with Arduino.

![Arduino board](images/arduino.png#left-leader)

The Arduino is a microcontroller platform that makes it easy to create
interactive electronics projects. In this tutorial, we'll use it to
control a simple LED.

## Circuit Diagram

![Circuit breadboard layout](images/breadboard.png#breadboard)
<div class="caption">Figure 1: Connect the LED to pin 13 with a 220Ω resistor</div>

## Additional Resources

[![Arduino icon](images/arduino.png#icon-indented) Official Arduino documentation](https://www.arduino.cc/reference/)

[![Tutorial icon](images/tutorial.png#icon-indented) Sparkfun LED tutorial](https://learn.sparkfun.com/tutorials/light-emitting-diodes-leds)

Example 2: Reference Page with Tables

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Python Data Types

---

| Type | Example | Description |
|------|---------|-------------|
| `int` | `42` | Integer numbers |
| `float` | `3.14` | Decimal numbers |
| `str` | `"hello"` | Text strings |
| `bool` | `True` | Boolean values |

Example 3: Documentation with Admonitions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# System Requirements

!!! pied-piper "Important Configuration"
    Make sure to set the environment variables before starting the service.

    ```bash
    export DATABASE_URL="postgresql://localhost/mydb"
    export SECRET_KEY="your-secret-key"
    ```

![System architecture](images/architecture.png#centred)
<div class="caption">Figure 1: The complete system architecture</div>
<div class="attribution">Based on the reference implementation by Johnson et al. (2024)</div>

Example 4: Comparison Layout

1
2
3
4
5
6
7
8
9
# Two Approaches

<hr class="two-equal-columns">

| Approach A | Approach B |
|------------|------------|
| ![Diagram A](images/a.png#figure) | ![Diagram B](images/b.png#figure) |
| Uses synchronous processing | Uses asynchronous processing |
| Simpler to understand | Better performance |

Configuration in mkdocs.yml

To use these stylesheets in your MkDocs project, add them to your mkdocs.yml:

1
2
3
4
5
6
extra_css:
  - static/common.css
  - static/slide.css
  - static/iot.css
  - static/db.css
  - static/opsman.css

Required markdown extensions:

1
2
3
4
5
6
markdown_extensions:
  - attr_list        # Required for CSS classes
  - tables           # Required for table support
  - md_in_html       # Required for HTML elements
  - admonition       # Required for admonitions
  - pymdownx.details # Required for collapsible sections

Tips and Best Practices

  1. Use URL fragments for images - It's cleaner than writing HTML with class attributes
  2. Test responsive behavior - Some styles (like #left-leader) may not work well on mobile
  3. Combine styles carefully - Not all styles are meant to be combined
  4. Use semantic markup - Even with custom CSS, maintain proper HTML structure
  5. Check Material theme version - Some Material overrides may need adjustment for newer versions
  6. Optimize images first - CSS can size images, but start with appropriately-sized source files
  7. Consider accessibility - Ensure sufficient color contrast and provide alt text
  8. Preview before publishing - Run mkdocs serve to preview how styles render

Browser Compatibility

These stylesheets use modern CSS features including: - CSS Grid and Flexbox - CSS Variables - Attribute selectors - Pseudo-elements

Tested and working in: - Chrome/Edge 90+ - Firefox 88+ - Safari 14+

Troubleshooting

Images not styling correctly

  • Ensure the fragment identifier is spelled correctly (case-sensitive)
  • Check that the CSS file is loaded in mkdocs.yml
  • Verify the image path is correct

Tables not displaying as expected

  • Make sure you have the tables markdown extension enabled
  • Check that the horizontal rule (---) is on its own line for header suppression
  • Verify proper markdown table syntax

Slide mode not working

  • Ensure slide.js is included in extra_javascript
  • Check browser console for JavaScript errors
  • Verify the slide trigger elements are properly marked

Admonitions not displaying

  • Confirm admonition markdown extension is enabled
  • Check that the admonition type is spelled correctly
  • For custom admonitions like pied-piper, ensure opsman.css is loaded

Summary

The custom CSS stylesheets provide extensive formatting options for MkDocs markdown content:

  • Image styling via URL fragments - Easy to apply without HTML
  • Responsive layouts - Float, centre, and size images appropriately
  • Table customizations - Suppress headers, force column widths, add styling
  • Caption system - Professional figure captions and attributions
  • Presentation mode - Full-screen slide display
  • Material theme integration - Enhanced styles for Material for MkDocs

These styles enable rich, professional documentation while maintaining the simplicity of markdown writing.