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.

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 (Deploy MkDocs with Material or Material Insiders theme to Vercel - Deborah Barnard), we can also use package.json and requirements.txt to automatically deploy Material for MkDocs on Vercel (在线发布 - 建站指南).

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

{
    "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.

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.

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.

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 (Add Vercel Analytics provider · Issue #6377 · squidfunk/mkdocs-material). The html code can be found in Vercel Web Analytics and Speed Insights Overview.

<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.

extra:
  analytics:
    provider: vercel

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

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.

This article is based on commit 7624e78 at Jan 6, 2024; code changes may occur in subsequent versions. Then remove the code as shown below.

<!-- 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 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.

extra:
  custom_dir: overrides

For removing the logo specifically from the navigation sidebar (mobile menu), you can modify the navigation template and add custom CSS instead of editing the header template.

Create a new html partial file overrides/partials/nav.html and copy the code in mkdocs-material/src/templates/partials/nav.html to the new file. Then modify the navigation title section:

<label class="md-nav__title" for="__drawer">
  <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" aria-label="{{ config.site_name }}">
    {{ config.site_name }}
  </a>
</label>

Add the following CSS to docs/stylesheets/extra.css to hide the logo button and adjust the padding:

/* Navigation title customization - hide logo button */
.md-nav__title .md-nav__button.md-logo {
    display: none !important;
}

/* Reduce top padding for navigation title after removing logo */
.md-nav__title {
    padding: 40px 16px 4px !important;
}

This approach removes the logo from the navigation title while preserving the clickable site name link and adjusting the spacing for a cleaner appearance.

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. This method offers greater flexibility for individual image settings. Additionally, it can intergrate with HTML and CSS to create more complex layouts.

<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 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.

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.

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. You can also set for slate scheme by setting data-md-color-scheme="slate". Similar settings can be applied in the subsequent sections.

[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;
}

theme:
  name: material
  palette:
    - scheme: default
      toggle:
        icon: material/weather-night
        name: Light mode

Result:

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.

[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. 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.

Deploying on Vercel

Setting up Vercel Analytics

Enable Vercel Analytics

Customizing analytics settings

Removing header logo

Alternative: Removing navigation logo

Glightbox configuration

Manual trigger

HTML syntax

Customizing theme colors

Primary color

Important colors

Other colors