CRUD.cloud

Fix Missing Nerd Font Icons in MkDocs

Update, October 2026: I'm keeping this article as I wrote it in 2021. Some things have changed since then, so read Before You Try This Today before you copy the commands.

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.

Before You Try This Today

Added on 2026-10-20. The article above is unchanged since 2021-02-01; these are the gotchas you may hit if you follow it today.

  • Material for MkDocs has a supported way to set the code font. Instead of font-family: ... !important on code, pre, kbd, samp, keep the @font-face and set the theme's CSS variable: :root { --md-code-font: "MesloLGS Nerd Font"; }. The Material docs advise defining fonts through CSS variables, not font-family, so the system font fallback keeps working.
  • Nerd Fonts v3 (2023) moved icons. It dropped the old nf-mdi-* Material Design codepoints (the F500 range) in favour of nf-md-* codepoints starting at F0001. An icon copied from an older prompt can still show as tofu with a current font, and the reverse. Use the same Nerd Fonts version on your terminal and on the site.
  • If you follow the .woff2 tip, change the CSS too. The example still loads the .ttf. Point src at the new file with format('woff2'), or the browser keeps downloading the larger one.
  • Self-hosting a font means shipping it. Meslo and Nerd Fonts are openly licensed, but keep their licence file next to the font in docs/assets/fonts/.

References

Links checked on 2026-10-20.