Mkdocs-material: Update Font Awesome to 5.0 – breaking change

[Sharom]

Please, update Font Awesome to version 5.0.

Gitter icon was added since 5.0 ;)

[squidfunk]

This would break the Material integration because now there are multiple prefixes .fa, .fab etc. which Material doesn't know about, so configuration would change which in turn would mean an entirely new release. I will keep this in mind for 3.0.0 but it's probably not gonna happen anytime soon.

[Sharom]

Ok, thank your for the answer.

[iamtraction]

@squidfunk It's not breaking the Material integration. I've started using Font Awesome 5 in one of my mkdocs-material site.

The only place it needed to be changed is in the social.html partial file. And there are also some references to old Font Awesome prefix, fa, in the docs.
Isn't it all? Or am I missing something here?

I was actually going to make a PR for Font Awesome 5, now, but then I saw this issue, and thought that I discuss it before I open the PR.

[squidfunk]

As I understood, the .fa prefix now is not universal but sometimes an icon needs the .fa, sometimes the .fab prefix. This would mean we need to change the way social links are configured in mkdocs.yml, as currently only the second part of the Font Awesome Glyph (i.e. github for .fa .fa-github) needs to be defined. This means the user has to adjust their mkdocs.yml to .fab .fa-github (for example), or am I mistaken?

[iamtraction]

There are 4 icon sets in Font Awesome 5, namely Brands, Solid, Regular & Light. And they have different prefixes - .fab, .fas, .far & .fal, respectively.
And the old .fa prefix is now just an alias of the .far prefix. So, the .fa & .far are now only for the Regular icon set.

And no, we don't need to change anything for the mkdocs.yml, because the users only define social icons in the mkdocs.yml like:

extra:
  social:
    - type: 'github'
      link: 'https://github.com/...'
    - type: 'twitter'
      link: 'https://twitter.com/...'
    - type: 'discord'
      link: 'https://discord.gg/...'

They don't define the Font Awesome prefix there.

So we only need to make a few changes to the src/partials/social.html file, i.e. add new CDN link for Font Awesome 5 and change the prefix from .fa to .fab (since .fab is for brands & all social links are brand links), and it'll work, and there's no breaking change.

In one of my repository, I've overwritten the src/partials/social.html file and made the above mentioned changes so that I can use Font Awesome 5 and the new brand icons that're available with it. If you want I can point you to it, if you want to see an working example before proceeding with this change.

[squidfunk]

Hmm, so if we don't change the way it's integrated we limit usage to the brand icons. What if somebody wants to use another icon like the globe for a blog? That wouldn't be possible without extending the theme.

[iamtraction]

Yeah, if they want to use any other icons besides the brand icons, that wouldn't be possible with this way.

Another way to do this is by adding another option to mkdocs configuration file, to check if it's a brand icon, like:

extra:
  social:
    - type: 'globe'
      link: 'https://example.com/blog'
      brand: false
    - type: 'twitter'
      link: 'https://twitter.com/...'
      brand: true

Then in the social.html file we can use the .fab prefix if brand is set to true in the mkdocs config, otherwise we can use either of .fas, .far or .fal prefix (all those have same set of icons, but with different font weight). This would allow users to use all the icons offered by Font Awesome.

[pascalandy]

Hey guys,
Font Awesome thought about people using FA v4 who wants to make sure to not break stuff while upgrading to v5. You can use v4-shims.css. See docs.

This is what I use in my themes:

<!-- CSS Icon via fontawesome 5 -->
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.1/css/v4-shims.css">
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.1/css/all.css" integrity="sha384-gfdkjb5BdAXd+lj+gudLWI+BXq4IuLW5IT+brZEZsLFm++aCMlF1V92rMkPaX4PP" crossorigin="anonymous">

Cheers!

[proofit404]

Hi,

How could I help to make this happen?

Personally, I prefer to infer prefix from the type option in mkdocs.yml. So we will keep all the magic under the hood without changing any existed project configuration. Maybe it'll require some Python code.

Regards,
Artem.

[squidfunk]

Thanks for your offering. We haven't really settled on an implementation yet. If you want to go ahead on this a good start would be to draft a proposal which addresses the following topics:

• Users should be able to use all of Font Awesome, not only the brand or regular icon set
• Upgrading should be as easy as possible, ideally without a major release

Thus, coming up with a good design and upgrade path is crucial.

I haven't come up with a way of doing this without breaking everything down the line. Essentially, every downstream project would need to adjust its configuration, if done properly. This would mean a major release which I don't want to do solely for Font Awesome which is one of the main reason why this issue is unresolved for such a long time.

[coliff]

FYI: Font Awesome recently changed the way they offer the icons via their CDN. It's all done via JS now and they don't appear to offer CSS directly like they previously did. You need to create a kit.The advantage is that it includes both regular icons and brand icons (and can optionally include Font Awesome 4 compatibility too)
https://fontawesome.com/start

[squidfunk]

Okay, so as I understand we should consider building a kit. This means we could also bundle it with the theme which would be better in terms of GDPR.

[coliff]

I think the kits are only available via their CDN though. You can download the fonts and CSS still though and use it with <link href="/your-path-to-fontawesome/css/all.css" rel="stylesheet">

https://fontawesome.com/how-to-use/on-the-web/setup/hosting-font-awesome-yourself

[darrenhaken]

I'm struggling to get Font Awesome working (new to MkDocs).

There a project to support font awesome but it's not working. Is this due to this issue with the theme?

[Stanzilla]

Any chance an update to v4 could be pushed with a newer font awesome version? Current is missing the Discord icon, afaik.

[squidfunk]

@Stanzilla you could override footer.html and override it directly in the template. As my previous comments suggest, upgrading it will induce a major release, so there‘s nothing we can do before v5.

[squidfunk]

704a7c50 upgrades FontAwesome to the latest version on the refactoring branch and switches to the SVG version of FontAwesome. This means that all icons are inlined with the HTML reducing the payload by a huge margin. The configuration now just mirrors the folder structure:

social:
    - type: brand/twitter
      link: 'https://twitter.com/...'
    - type: brand/linkedin
      link: 'https://linkedin.com/...'

Will yield:

<a href="https://twitter.com/squidfunk" class="md-footer-social__link">
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 512">
    <path d="M186.1 328.7c0 20.9-10.9 55.1-36.7 55.1s-36.7-34.2-36.7-55.1 10.9-55.1 36.7-55.1 36.7 34.2 36.7 55.1zM480 278.2c0 31.9-3.2 65.7-17.5 95-37.9 76.6-142.1 74.8-216.7 74.8-75.8 0-186.2 2.7-225.6-74.8-14.6-29-20.2-63.1-20.2-95 0-41.9 13.9-81.5 41.5-113.6-5.2-15.8-7.7-32.4-7.7-48.8 0-21.5 4.9-32.3 14.6-51.8 45.3 0 74.3 9 108.8 36 29-6.9 58.8-10 88.7-10 27 0 54.2 2.9 80.4 9.2 34-26.7 63-35.2 107.8-35.2 9.8 19.5 14.6 30.3 14.6 51.8 0 16.4-2.6 32.7-7.7 48.2 27.5 32.4 39 72.3 39 114.2zm-64.3 50.5c0-43.9-26.7-82.6-73.5-82.6-18.9 0-37 3.4-56 6-14.9 2.3-29.8 3.2-45.1 3.2-15.2 0-30.1-.9-45.1-3.2-18.7-2.6-37-6-56-6-46.8 0-73.5 38.7-73.5 82.6 0 87.8 80.4 101.3 150.4 101.3h48.2c70.3 0 150.6-13.4 150.6-101.3zm-82.6-55.1c-25.8 0-36.7 34.2-36.7 55.1s10.9 55.1 36.7 55.1 36.7-34.2 36.7-55.1-10.9-55.1-36.7-55.1z"></path>
  </svg>
</a>
...

It's a breaking change, but v5 will be breaking anyway. Furthermore, FontAwesome is now installed via npm, which means keeping it up-to-date just got super easy. I'm releasing a preview version of v5 later this day. See #1306 for more.

[squidfunk]

Just released 5.0.0b1 which includes the new FontAwesome integration, see #1465 - any feedback is appreciated

[squidfunk]

Material for MkDocs 5.0.0rc1 is out which fixes this issue 😀 Let's test and improve it together!