When working on documentation for my product, LiveAPI, I started using MkDocs, a static site generator that produces clean and professional documentation.
However, I found its design a bit monotonous and decided to explore the project to make some customizations.
This journey led me to an intriguing part of its architecture: Sass maps.
What started as a casual modification turned into a deeper appreciation for the thoughtful design behind this project.
In this blog, I’ll explore how Sass maps are used in MkDocs’ Material theme—specifically, in its mixins—and how they contribute to the flexibility and scalability of the design system. Let’s dive in!
What Are Sass Maps?
Sass maps are a key-value data structure in Sass, akin to dictionaries in Python or objects in JavaScript.
They allow us to store related data compactly and retrieve values dynamically.
In the MkDocs Material theme, Sass maps are used to define device-specific breakpoints for responsive design. For example:
@use "sass:map";
@use "sass:list";
@use "sass:math";
$break-devices: (
mobile: (
portrait: 220px 479px,
landscape: 480px 719px,
),
tablet: (
portrait: 720px 959px,
landscape: 960px 1219px,
),
screen: (
small: 1220px 1599px,
large: 1600px 1999px,
),
) !default;
This map organizes breakpoints into categories (mobile, tablet, screen) and subcategories (portrait, landscape, small, medium, large).
It’s not just a static definition—it’s the backbone of how responsive behaviors are generated dynamically.
How Sass Maps Work in MkDocs Mixins
The theme uses a series of functions and mixins to extract and utilize data from the $break-devices map. Here’s a breakdown:
1. Extracting Breakpoint Values
The break-select-device function traverses the map to find the relevant device category and retrieves the associated breakpoints.
If multiple levels are specified (e.g., mobile portrait), it digs deeper into the hierarchy.
@function break-select-device($device) {
$current: $break-devices;
@for $n from 1 through length($device) {
@if type-of($current) == map {
$current: map.get($current, list.nth($device, $n));
} @else {
@error "Invalid device map: #{$devices}";
}
}
@return $current;
}
-
@for Loop: This loop runs from the first to the last item in the
$devicelist, ensuring every level in the hierarchy is checked. - @if Condition: This checks if the current value is still a map and continues digging if true. If not, it halts with an error message.
-
map.get: A built-in Sass function that retrieves a value from the map using a key.
2. Creating Media Queries
In SCSS, a mixin is a reusable block of code that you can define once and use throughout your stylesheet.
It helps keep your code DRY (Don't Repeat Yourself) by allowing you to include styles or logic multiple times without repeating the code.
For example, if you need to apply a set of styles repeatedly, you can create a mixin and reuse it wherever required:
The break-from-device and break-to-device mixins leverage this function to dynamically generate media queries. For instance:
@mixin break-from-device($device) {
@if type-of($device) == string {
$device: $device;
}
@if type-of($device) == list {
$breakpoint: break-select-device($device);
$min: list.nth($breakpoint, 1);
@media screen and (min-width: $min) {
@content;
}
} @else {
@error "Invalid device: #{$device}";
}
}
@mixin break-to-device($device) {
@if type-of($device) == string {
$device: $device;
}
@if type-of($device) == list {
$breakpoint: break-select-device($device);
$max: list.nth($breakpoint, 2);
@media screen and (max-width: $max) {
@content;
}
} @else {
@error "Invalid device: #{$device}";
}
}
This mixin applies styles for a minimum width specified in the map. A similar approach is used for the break-to-device mixin, which targets a maximum width.
Applying the Mixins
To see the power of the break-from-device and break-to-device mixins, let’s look at practical examples of how to use them to implement responsive styles dynamically.
Example 1: Applying Default Styles for Mobile Devices
By default, we apply styles for mobile screens using a grid layout that works well on small screens without the need for a mixin. For example:
.grid {
display: grid;
gap: 16px;
grid-template-columns: repeat(1, 1fr); /* 1 column for small screens */
}
In this case, the layout is already optimized for mobile devices. The base styles cater to mobile users by default.
To enhance responsiveness for larger screens, you can use the break-from-device mixin to target specific breakpoints.
Example 2: Targeting Tablet Landscape
On smaller screens, such as tablets up to the landscape breakpoint, certain elements like the sidebar may not fit well due to limited screen space.
In such cases, we can hide the sidebar and show it as a popover from left to prioritize the main content. For example:
@include break-to-device(tablet landscape) {
.sidebar {
display: none;
}
}
-
tablet landscape: Refers to thetabletcategory and itslandscapesubcategory in the$break-devicesmap. - The generated media query will be:
@media screen and (max-width: 1219px) {
.sidebar {
display: none;
}
}
For devices larger than the tablet landscape breakpoint, where more screen space is available, we can introduce a two-column layout for improved content distribution. This can be achieved using the break-from-device mixin:
@include break-from-device(("tablet", "landscape")) {
.grid {
grid-template-columns: repeat(
2,
1fr
); /* 2 columns for tablets and larger screens */
}
}
- The generated media query will be:
@media screen and (min-width: 1220px) {
.grid {
grid-template-columns: repeat(
2,
1fr
); /* 2 columns for tablets and larger screens */
}
}
Example 3: Targeting Desktops
As screen sizes increase, more space becomes available to present content.
For desktops, we can adjust the grid layout to create three or four columns, depending on the screen size, using the break-from-device mixin.
For small desktops:
When the screen size is large enough to accommodate three columns, the following styles apply:
@include break-from-device(("desktop", "small")) {
.grid {
grid-template-columns: repeat(3, 1fr); /* 3 columns for small desktops */
}
}
-
desktop small: Refers to thedesktopcategory and itssmallsubcategory in the$break-devicesmap. - The generated media query will be:
@media screen and (min-width: 1440px) {
.grid {
grid-template-columns: repeat(3, 1fr);
}
}
For large desktops:
For even larger screens, we can create four columns to maximize the use of screen real estate:
@include break-from-device(("desktop", "large")) {
.grid {
grid-template-columns: repeat(4, 1fr); /* 4 columns for large desktops */
}
}
-
desktop large: Refers to thedesktopcategory and itslargesubcategory in the$break-devicesmap. - The generated media query will be:
@media screen and (min-width: 1920px) {
.grid {
grid-template-columns: repeat(4, 1fr);
}
}
Architectural Elegance
This design shows the author’s intent to prioritize scalability and maintainability.
By abstracting breakpoints into a single source of truth and using mixins for media queries, they’ve created a system that:
- Is Easy to Maintain: Updating breakpoints or adding new ones doesn’t require hunting through the codebase.
- Enhances Readability: Media queries are abstracted into logical, reusable components.
- Promotes Scalability: New devices or categories can be added to the map without breaking existing functionality.
Final Thoughts
Exploring MkDocs Material has deepened my appreciation for thoughtful design in front-end architecture.
The use of Sass maps, mixins, and hierarchical data structures is a masterclass in maintainable and scalable design systems.
If you’re looking to create or improve your own responsive styles, consider adopting similar techniques.
Have you encountered or used Sass maps in your projects? I’d love to hear your experiences and insights!
Want to dive deeper into the designing world? Check out our other blog posts:
- Basic Rules of Design for Non-Designers
- Powerful UI Design and Implementation Principles
- Making Great Widgets
Subscribe for a weekly dose of insights on development, IT, operations, design, leadership and more.
Top comments (0)