Optimize CSS size

[weeblr]

Hello,

I have done a simple website with a few pages, with a simple mkdocs.yml (see below) and I'm surprised to find that the compiled main.css file is a massive 126KB (zips down to about 20+K), with another 13KB palette.css file as well.

Looking into it, it appears to include CSS that's not at all used on the site.

In addition, commenting out all features and markdown_extensions do not change at all the built CSS files, the CSS is exactly the same.

Is there a way to apply purgeCSS or similar as part of the build to get rid of all unused selectors?

Thanks and regards

mkdocs.yml:

site_name: Example
site_url: https://www.example.com/
site_dir: public
theme:
  name: material
  custom_dir: overrides/
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: white
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  logo: https://assets.example.com/logo.png
  favicon: _images/favicon-32x32.png
  features:
    # Instant navigation breaks Cloudflare email protection
    #    - navigation.instant
    #    - navigation.instant.progress
    - navigation.tabs
    - navigation.path

plugins: []

extra:
  homepage: https://www.example.com

extra_css:
  - '_assets/fonts.css'
#  - '_assets/styles.css'
#extra_javascript:
#  - '_assets/code.js'

markdown_extensions:
  - tables
  - meta
#  - admonition
  #  - codehilite:
  #      linenums: true
  #  - footnotes
#  - attr_list
  - pymdownx.betterem:
      smart_enable: all
  #  - pymdownx.caret
  #  - pymdownx.critic ## does not play well with blade templates comments syntax
  - pymdownx.details
  #  - pymdownx.inlinehilite
  #  - pymdownx.mark
  #  - pymdownx.superfences
  #  - pymdownx.tasklist:
  #      custom_checkbox: true
  #- pymdownx.tilde

nav:
  - Home: 'index.md'
  - Page 1: 'content/index.md'
  - Page 2: 'content/page-2.md'
  - Page 3: 'content/page-3.md'
  - About: 'about.md'

[alexvoss]

The CSS is bundled at the time the theme is built, so it would be difficult to unpack this. It is conceivable to identify any larger components and break them out.

Having said that, can you explain why 126KB that gets loaded once and then cached is troublesome? Bear in mind that I am not a web designer, so have no sense of measure here.

When I look at the log of network activity for some commercial sites, Material looks pretty lean and mean in comparison. The only reason pages take any time at all to load is because I run a lone AWS instance and not a CDN.

[squidfunk]

It is impossible for us to know what CSS is used by the author, as MkDocs does not identify which components are used – there's no frontend-buildstep involved. This means we must ship everything to the user. There's no way we can reduce it. Other than that, we're always trying and keep things as minimal as possible, but with the many features that this project offers, the code base consistently grows.

What could be done in theory is a plugin that identifies which CSS has actually been used by running purge CSS or some other tool as a build step, so it doesn't end up in the final site. It's a perfect match for a third-party plugin!

[squidfunk]

FWIW, Docusaurus is quite comparable with 112kb (26kb gzipped):

[weeblr]

Hi Martin,

First off, thanks for a great piece of software!

What could be done in theory is a plugin that identifies which CSS has actually been used by running purge CSS or some other tool as a build step, so it doesn't end up in the final site. It's a perfect match for a third-party plugin!

Such tool already exists, it's PurgeCss and running it as a build step after mkdocs build works fine, essentially cutting in half the css size in my specific use case.

But PurgeCss is javascript (needs nodejs) and so I assume directly integrating it into mkdocs is not possible.
I don't know if there's such a tool in Python but then maybe just documenting the above would be enough for most people?

Cheers

[squidfunk]

But PurgeCss is javascript (needs nodejs) and so I assume directly integrating it into mkdocs is not possible.

Via a system call, definitely. However, it's nothing we consider adding to our code base, because Node.js as a new dependency will throw a lot of people off. This piece of software is so popular because it doesn't need a JS runtime.

We're not considering adding this to our documentation, as it's the very first time we heard of this and don't consider it a common case. 20kb gzipped is absolutely okay, IMHO, so likely not a big problem for 99% of users.

[weeblr]

No problem, I still prefer reducing all that's sent over the wire but I'm happy adding PurgeCSS was simple and does the job.

[couleurm]

How could that be used in GitHub actions? It seems mkdocs gh-deploy builds AND deploys, is there a way to run this after building but before deploying?

[alexvoss]

If you want to run external code like PurgeCSS from within MkDocs then the easiest way is to use hooks. You would attach to the on_post_build event in this case.

[kamilkrzyskow]

You don't have to use the gh-deploy to build and deploy at the same time, you can use mkdocs build and then execute the PurgeCSS in CI and later run some GitHub Action which will deploy the files for you.
The projects' documentation uses artifact based deployment without the gh-pages branch:

mkdocs-material/.github/workflows/documentation.yml

Lines 92 to 112 in 15f1506

	- name: Build documentation
	env:
	GH_TOKEN: ${{ secrets.GH_TOKEN }}
	GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
	run: |
	mkdocs build --clean
	mkdocs --version
	- name: Adjust permissions
	run: |
	chmod -c -R +rX site/ | while read line; do
	echo "::warning title=Invalid file permissions automatically fixed::$line"
	done
	- name: Upload to GitHub Pages
	uses: actions/upload-pages-artifact@v3
	with:
	path: site
	- name: Deploy to GitHub Pages
	uses: actions/deploy-pages@v4

But there are for sure other options in the actions marketplace ✌️