|
| 1 | +--- |
| 2 | +title: WordPress Configurations Guide |
| 3 | +subtitle: Using the WordPress Font Library on Pantheon |
| 4 | +description: Understand how to use the WordPress Font Library on Pantheon and how to restore the WordPress default behavior. |
| 5 | +contenttype: [guide] |
| 6 | +innav: [false] |
| 7 | +categories: [config] |
| 8 | +cms: [wordpress] |
| 9 | +audience: [development] |
| 10 | +product: [--] |
| 11 | +integration: [plugins] |
| 12 | +tags: [workflow, code] |
| 13 | +contributors: [jazzsequence] |
| 14 | +permalink: docs/guides/wordpress-configurations/wordpress-font-library |
| 15 | +--- |
| 16 | + |
| 17 | +This section provides information on how to use the WordPress Font Library on Pantheon. |
| 18 | + |
| 19 | +WordPress 6.5 introduces a new [Font Library](https://make.wordpress.org/core/2024/03/14/new-feature-font-library/) feature. The Font Library allows you to upload fonts from your computer or add any of the fonts available on Google's font library to your WordPress site. In anticipation of this, Pantheon has added a feature to our [Pantheon MU Plugin](https://github.com/pantheon-systems/pantheon-mu-plugin) to store those fonts in a writeable directory (`wp-content/uploads/fonts/`), so that you can use the feature without any issues after updating your sites to 6.5. |
| 20 | + |
| 21 | +By default, WordPress will install fonts into `wp-content/fonts/` if it is writeable. If `wp-content/fonts/` is not writeable, like on Pantheon environments, WordPress will install fonts into `wp-content/uploads/fonts/`. This can create inconsistency when developing locally if WordPress is using its default behavior because your `wp-content/fonts/` is likely to be writeable on your local environment. In this instance, fonts installed _on Pantheon_ would be stored in `wp-content/uploads/fonts` but fonts installed _locally_ would be stored in `wp-content/fonts`, which is why we have altered the behavior in the mu-plugin. |
| 22 | + |
| 23 | +## Using the `font_dir` Filter |
| 24 | + |
| 25 | +You can change the directory where fonts are stored by using the WordPress core filter `font_dir` like this: |
| 26 | + |
| 27 | +```php |
| 28 | +add_filter( 'font_dir', function( $defaults ) { |
| 29 | + $font_dir = '/path/to/your/custom/dir'; |
| 30 | + $font_url = site_url( $font_dir ); |
| 31 | + |
| 32 | + $defaults['path'] = $font_dir; |
| 33 | + $defaults['url'] = $font_url; |
| 34 | + $defaults['basedir'] = $font_dir; |
| 35 | + $defaults['baseurl'] = $font_url; |
| 36 | + |
| 37 | + return $defaults; |
| 38 | +} ); |
| 39 | +``` |
| 40 | + |
| 41 | +The default priority for WordPress filters is `10`. We have set _our_ `font_dir` filter to priority `9` so it allows you to override our modification. |
| 42 | + |
| 43 | +## Considerations |
| 44 | + |
| 45 | +WordPress handles fonts more like **media files** than **plugins or themes**. This means that when fonts are added to one Pantheon site environment, they will not necessarily exist in your other environments (e.g. installing a font on Dev does not mean it will push to Test when you deploy). In WordPress, fonts have two parts, there is a font post type (similar to the `attachment` post type for media files) and the font files themselves. Without the font post type existing in the database, WordPress has no way of knowing that a font is installed (in the same way that WordPress has no way that a particular image exists in the `/uploads` directory if it was not uploaded via the media library). |
| 46 | + |
| 47 | +If you intend to override the Pantheon behavior, know that committing font files to your repository will not make them available automatically on your other environments. |
| 48 | + |
| 49 | +## Troubleshooting |
| 50 | + |
| 51 | +### "No font faces were installed" error message |
| 52 | + |
| 53 | + |
| 54 | + |
| 55 | +If you have altered the `font_dir` path and are uploading to a directory that is not writeable, you may see this error message. Ensure that the directory you are using in your `font_dir` filter is writeable (e.g. in `wp-content/uploads/`). |
| 56 | + |
| 57 | +### I've cloned my database from Live and my font is installed but not "active" |
| 58 | + |
| 59 | + |
| 60 | + |
| 61 | +If you've cloned your database and files from your live environment to Dev or Test and the font appears in your Font Library but is not "active" (it displays a message like "0/1 variants active"), you can click into the font, select the variant you want, and click update. |
| 62 | + |
| 63 | + |
| 64 | + |
| 65 | +Whether or not a font is "active" is similar to whether or not a plugin or theme is active. If a font is not active, it means the font is installed and recognized by WordPress but it cannot be used on the site until you activate it. |
| 66 | + |
| 67 | +### I've uploaded fonts to my `/fonts` directory, but they aren't showing up in the Font Library |
| 68 | + |
| 69 | +Fonts need to be installed via the Font Library in the WordPress admin. This is because fonts contain data that is stored in a post type. Simply having a font in your `/fonts` directory does not mean it will be recognized by WordPress. See [this Gutenberg issue](https://github.com/WordPress/gutenberg/issues/59102) to track this in WordPress core. |
| 70 | + |
| 71 | +## More Resources |
| 72 | +* [New Feature: Font Library](https://make.wordpress.org/core/2024/03/14/new-feature-font-library/) |
| 73 | +* [Font Library Gutenberg Tracking Ticket](https://github.com/WordPress/gutenberg/issues/55277) |
0 commit comments