Skip to content

Material for MKDocs Advanced Customization

This article provides a step-by-step guide to advanced customization of Material for MkDocs. It includes deploying on Vercel, setting up Vercel Analytics, removing header logo, GLightbox configuration, and customizing theme colors.

Note

This article assumes you have a basic understanding of HTML, CSS, and JavaScript. If you're not familiar with these technologies, it's highly recommended to read Modern HTML Explained For Dinosaurs, Modern CSS Explained For Dinosaurs, and Modern JavaScript Explained For Dinosaurs first. Also, this article assumes a basic understanding of Material for MkDocs. It's beneficial to have a quick overview of "Getting started", "Setup", "Plugins" and "Reference" sections. Here is a Quick Start Guide for novice users.

Deploying on Vercel

As shown in the official documentation Publishing your site, Material for MkDocs can be easily deployed on Github Pages, Netlify, Vercel and other satatic site hosting services.

Besides manually setting Build & Development Settings on Vercel dashboard to deploy site 1, we can also use package.json and requirements.txt to automatically deploy Material for MkDocs on Vercel 2.

Adding package.json and requirements.txt to the root directory of the project.

package.json
{
    "name": "mkdocs",
    "version": "1.0.0",
    "private": true,
    "scripts": {
        "dev": "mkdocs serve",
        "build": "mkdocs build -d public"
    },
    "engines": {
        "node": "18.x"
    }
}

The build script will build the site to the public directory which is the default publish directory of Vercel.

Note

The node version should be set to 18.x to avoid compatibility issues.

requirements.txt
mkdocs-material
mkdocs
mkdocs-glightbox
mkdocs-rss-plugin
urllib3<2

The requirements.txt file lists the required python packages for the site. mkdocs-material and mkdocs are the core packages, mkdocs-glightbox used for image lightbox and mkdocs-rss-plugin used for generating RSS feed.

Note

urllib3<2 is required to avoid the ImportError: urllib3 v2 only supports OpenSSL 1.1.1+ error when deploying rss plugin on Vercel with node version 18.x.

Then push the changes to the github repository and Vercel will automatically deploy the site based on these configurations.

Setting up Vercel Analytics

The official documentation only provides a guide Setting up site analytics for adding Google Analytics to site. Here is a step-by-step guide to setting up Vercel Web Analytics and Speed Insights Overview for site.

Warning

Using Vercel services should deploy the site on Vercel, please refer to #Deploying on Vercel.

Enable Vercel Analytics

Enable Vercel Analytics and Speed Insights for related project on Vercel dashboard. It has a free Hobby plan for all users.

Customizing analytics settings

Create a new html patial file overrides/partials/integrations/analytics/vercel.html and add the following code 3. (1)

  1. The html code can be found in Vercel Web Analytics and Speed Insights Overview.
vercel.html
<script>
    window.va = window.va || function () { (window.vaq = window.vaq || []).push(arguments); };
</script>
<script defer src="/_vercel/insights/script.js"></script>

<script>
    window.si = window.si || function () { (window.siq = window.siq || []).push(arguments); };
</script>
<script defer src="/_vercel/speed-insights/script.js"></script>

Add the following code to mkdocs.yml to enable Vercel Analytics.

mkdocs.yml
extra:
  analytics:
    provider: vercel

Then add the following code to mkdocs.yml to enable the customization.

mkdocs.yml
extra:
  custom_dir: overrides

Submit the updates to github and wait for Vercel deployment to complete, then visit your site and check analytics data and speed insights in Vercel dashboard.

Based on Customization section in official documentation, we can customize the different parts of the theme template.

For removing the header logo, we create a new html partial file overrides/partials/header.html first and copy the code in mkdocs-material/src/templates/partials/header.html to the new file.

Then remove the code as shown below. (1)

  1. This article is based on commit 7624e78 at Jan 6, 2024; code changes may occur in subsequent versions.
header.html
38
39
40
41
42
43
44
45
46
47
<!-- Link to home -->
<a
  href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
  title="{{ config.site_name | e }}"
  class="md-header__button md-logo"
  aria-label="{{ config.site_name }}"
  data-md-component="logo"
>
  {% include "partials/logo.html" %}
</a>

Add style="margin-left: .6rem;" to head_title to align left with navgation bar below.

header.html
55
56
57
58
<!-- Header title -->
<div class="md-header__title" data-md-component="header-title" style="margin-left: .6rem;">
  <div class="md-header__ellipsis">
    <div class="md-header__topic">

Add the following code to mkdocs.yml to enable the customization.

mkdocs.yml
extra:
  custom_dir: overrides

Glightbox configuration

MkDocs GLightbox is a MkDocs plugin supports image lightbox with GLightbox. It is used to handle images, vedios, iframes and inline content. The basic usage can be found in MkDocs GLightbox and Images - Material for MkDocs.

Manual trigger

It is advisable to set manual option to true and enable GLightbox manually in sepecific pages by adding glightbox: true in it's front matter. This can prevent image conflicts between blog post pages and external post directory pages, while also maintaining simplicity and prevent accidental trigger. I personally enable this option only in posts that display photography where images need to be enlarged for viewing.

HTML syntax

Besides using markdown syntax to include images, we can also use HTML syntax to include images with GLightbox 4. This method offers greater flexibility for individual image settings. Additionally, it can intergrate with HTML and CSS to create more complex layouts.

For example, the following code is excerpted from my publications page.

<div style="display: flex; width: 100%; height: 128px;">
  <div style="width: 70%; float: left; margin-right: 10px;">
    <span style="float: left; overflow-y: auto; max-height: 128px;">The immense scale of logs burdens storage resources and limits forensic analysis efficiency. Many offline algorithms require centralized processing in dedicated data servers exacerbating financial cost of network transmission. We present SOPR, an online audit log reduction technique designed to preserve traceability.</span>
  </div>
  <div style="width: 30%; float: right; overflow: hidden;">
  <a href="/images/publications/adma-2024.png" class="glightbox0" data-gallery="gallery-publication">
    <img src="/images/publications/adma-2024.png" alt="Image" style="height: 128px; width: auto; object-fit: cover;"/>
  </a>
  </div>
</div>

The immense scale of logs burdens storage resources and limits forensic analysis efficiency. Many offline algorithms require centralized processing in dedicated data servers exacerbating financial cost of network transmission. We present SOPR, an online audit log reduction technique designed to preserve traceability.

The above code creates a layout with text on the left and an image on the right. The image is wrapped in gallery-publication data-gallery for slideshow. It automatically adjusts to maintain the 30% width ratio. The image height is set to 128px to align with the text height on the left.

Customizing theme colors

The color customization provided by official documentation is rather vague. There are many color variables in the theme not detailed. The basic color customization is setting primary and accent colors in mkdocs.yml, the slate scheme is used for dark mode and the default scheme is used for light mode 5.

mkdocs.yml
theme:
  name: material
  palette:
    # Dark Mode
    - scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Dark mode
      primary: green
      accent: deep purple

    # Light Mode
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Light mode
      primary: blue
      accent: deep orange

More advanced color customization requires add extra CSS file at stylesheets/extra.css and enable it in mkdocs.yml as shown below. Now, we can configure more detailed color settings.

mkdocs.yml
extra_css:
  - stylesheets/extra.css

The color variables in the theme are somewhat complex, and there are some conflicts between different color setting methods. In the following sections, I will explain related color settings seperately through decomposing different parts of the site.

Primary color

The primary color is the most striking color in the header, navigation bar... The key elements are foreground color and background color. Here is a example of setting primary color to red for default scheme. (1)

  1. You can also set for slate scheme by setting data-md-color-scheme="slate". Similar settings can be applied in the subsequent sections.
extra.css
[data-md-color-scheme="default"] {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
  --md-primary-bg-color:               #5693d4;
  --md-primary-bg-color--light:        #0964c4;
}
mkdocs.yml
theme:
  name: material
  palette:
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Light mode

Primary color

Warning

The primary color setting in mkdocs.yml will overwrite the primary color setting in extra.css. The mkdocs.yml configuration above does not include a primary color field.

Important colors

There are some important colors that will significantly affect most of the content on the website (from my perspective). My webpages only modifys following colors to maintain a consistent color scheme.

extra.css
[data-md-color-scheme="default"] {
  /* Typeset `a` color shades */
  --md-typeset-a-color:                var(--md-primary-fg-color);

  /* Accent color shades */
  --md-accent-fg-color:                hsla(#{hex2hsl($clr-indigo-a200)}, 1);
  --md-accent-fg-color--transparent:   hsla(#{hex2hsl($clr-indigo-a200)}, 0.1);
  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);

  /* Footer color shades */
  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.45);
  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
}

The typeset a color is applied for links, while the accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. The footer color is used for the footer area. (1)

  1. Try to change these colors to see the effect!

Other colors

The theme's color palette is detailed in _colors.scss and _scheme.scss. These files include comments for different colors and provide the default values for both the default and slate schemes.


  1. Deploy MkDocs with Material or Material Insiders theme to Vercel - Deborah Barnard ↩

  2. 在线发布 - 建站指南 ↩

  3. Add Vercel Analytics provider · Issue #6377 · squidfunk/mkdocs-material ↩

  4. GLightbox ↩

  5. Getting Started with Material for MkDocs - jameswillett.dev ↩

Comments