Skip to content

Blog Post Title: Fix Missing Nerd Font Icons in MkDocs

If you’ve ever spent hours perfecting your Starship prompt or Zsh theme, you likely want your documentation to reflect that same professional look. However, when you paste those beautiful terminal snippets into MkDocs, you often end up with "tofu"—those annoying little boxes with hex codes inside.

Here is how to properly embed Meslo LG Nerd Font into your MkDocs site so your icons render perfectly every time.

The Problem: Why Icons Disappear

Web browsers don't natively ship with Nerd Fonts. When you use a character like the Git branch icon (), the browser looks at its default monospace font, realizes it doesn't have a drawing for that character, and displays a placeholder box instead.

To fix this, we need to treat the Nerd Font as a Web Font.

Step 1: Prepare Your Font Files

First, you need the font file. While you might have it installed on your system, your website visitors won't.

  1. Locate your font file (e.g., MesloLGSNerdFont-Regular.ttf).
  2. Place it in your MkDocs project under docs/assets/fonts/.

Pro Tip: For better performance, convert your .ttf to .woff2 using an online converter. It’s significantly smaller and faster to load.

Step 2: Configure MkDocs

Tell MkDocs to load a custom CSS file. Open your mkdocs.yml and add:

extra_css:
  - stylesheets/extra.css

Step 3: Write the Custom CSS

This is the "secret sauce." You must define the font and then force your code blocks to use it. Create docs/stylesheets/extra.css:

/* 1. Define the custom font face */
@font-face {
    font-family: 'MesloLGS Nerd Font';
    src: url('../assets/fonts/MesloLGSNerdFont-Regular.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;
    font-display: swap;
}

/* 2. Force Code Blocks to use it */
code, pre, kbd, samp {
    font-family: 'MesloLGS Nerd Font', SFMono-Regular, Consolas, monospace !important;
}

Why the !important? Themes like Material for MkDocs have high-priority CSS that sets the code font. Without !important, your custom font will be ignored.

Step 4: Verify and Refresh

After saving, run mkdocs serve. If you still see boxes:

  1. Hard Refresh: Press Cmd + Shift + R (Mac) or Ctrl + F5 (Windows).
  2. Check Paths: Ensure the url() in your CSS correctly points to where the font file lives relative to the CSS file.

Conclusion

Your documentation should be as visually expressive as your terminal. By explicitly defining your Nerd Font in the CSS and targeting the code selectors, you ensure that every Git branch, folder, and status icon is displayed exactly as intended.