Skip to content

Why My MkDocs CSS Changes Were Not Appearing

While customising The Homelab Site, I ran into a frustrating issue where changes to my extra.css file appeared to be completely ignored.

The CSS file was loading correctly, MkDocs was rebuilding the site, and the browser was referencing the stylesheet, yet none of the changes appeared on the live website.

After several rounds of troubleshooting, the cause turned out to be Cloudflare caching.

This page documents the issue and the solution in case it helps someone else.

The Symptoms

I was attempting to change page heading colours and image caption styling.

For example:

.md-typeset h1 {
    color: yellow !important;
    font-size: 80px !important;
}

The CSS file clearly contained the new rules, but the website continued displaying the old styling.

What I Checked First

Before blaming Cloudflare, I verified the basics.

Confirmed the CSS File Existed

Inside the MkDocs container:

docker exec -it thehomelabsite-mkdocs sh

cat /docs/docs/stylesheets/extra.css

The file contained the latest changes.

Confirmed MkDocs Was Loading the CSS

My mkdocs.yml contained:

extra_css:
  - stylesheets/extra.css

The stylesheet also appeared in the browser's HTML source.

Confirmed MkDocs Was Rebuilding

The container logs showed rebuilds every time the CSS file changed:

INFO - Detected file changes
INFO - Building documentation...

Confirmed the CSS Was Being Served

From the server:

curl https://thehomelabsite.com/stylesheets/extra.css

The output showed the updated CSS content.

The Real Cause

Cloudflare was serving a cached version of the stylesheet.

Even though:

  • MkDocs had rebuilt the site
  • The container had the correct CSS
  • The website was serving the correct CSS file

Cloudflare continued delivering an older cached version to visitors.

As a result, styling changes never appeared.

The Fix

Log into Cloudflare and purge the cache.

Navigate to:

Cloudflare
→ Your Domain
→ Caching
→ Purge Cache
→ Purge Everything

After the cache purge, the new stylesheet was immediately loaded and all CSS changes appeared correctly.

How I Confirmed It

Before purging the cache:

curl https://thehomelabsite.com/stylesheets/extra.css

showed the updated file, but the browser still displayed the old styling.

After purging the cache:

  • Heading colours updated
  • Font sizes updated
  • Custom caption styles appeared
  • The site matched the contents of extra.css

Lessons Learned

When CSS changes are not appearing:

  1. Verify the CSS file exists.
  2. Verify extra_css is configured correctly.
  3. Confirm MkDocs is rebuilding.
  4. Check browser developer tools.
  5. Verify the CSS file is being served.
  6. If everything looks correct, check Cloudflare caching.

Cloudflare caching can make it appear that MkDocs or CSS is broken when the problem is actually an outdated cached file.

My Recommendation

When making frequent CSS changes during site development:

  • Use browser Developer Tools with cache disabled.
  • Consider temporarily reducing Cloudflare cache duration.
  • If changes still do not appear, purge the Cloudflare cache before spending hours troubleshooting.

In my case, the CSS was correct all along. The cache was the problem.