127.0.1.1 {{fqdn}} {{hostname}}

I have no idea what it’s even trying to do with that.

What it does do is break a lot of things, because while 127.0.1.1 is a valid address (albeit weird to use instead of the canonical 127.0.0.1), in a standard Plesk system Nginx (that sits in front of Apache typically) is configured to listen only on the network interface(s) associated with your web server’s public IP address(es), not localhost¹. So if you try e.g. curl mydomain.com from inside your server hosting that very domain, you get a connection refused error (or it just times out with no response, depending on firewall settings).

The way I found out about this was when WordPress’s “cron” system silently stopped running tasks (because I use a real cron job to trigger it periodically, rather than relying on WordPress’s flaky built-in system). I subsequently also noticed that Broken Link Checker mistakenly reported every link within my own site as broken.

The solution

…is fairly simple – modify the template to remove the offending line. You then have to either reboot or similarly manually modify /etc/hosts to actually apply the fix.

If for some reason you cannot do that, there are potentially workarounds. For example, for curl commands you can make curl navigate around the problem this like:

In a non-Plesk environment you might also be able to just change the Nginx configuration (somewhere under /etc/nginx). That’s ill-advised for Plesk-operated servers as Plesk will inevitably revert your changes (and as far as I can tell there is no configuration option, or workaround otherwise, to make Plesk configure Nginx to listen on localhost as well 😕).

1. I suspect this is more a side-effect than intentional. Plesk chooses the interface only implicitly, when it specifies that it listens on specific addresses – those assigned to the website in question (Nginx can host multiple otherwise unrelated websites, and each is configured independently within its settings). Since Plesk supports hosting multiple websites, each with potentially different IP addresses, it makes sense that it would want to keep them separate. Otherwise, in a shared hosting situation you could connect to the IP address for somehost.com yet issue a HTTP request for unrelatedhost.com and actually get a response, which is weird, at least. ↩︎

WordPress relies on either ImageMagick or GD for its ability to read & write images. It prefers ImageMagick, as ImageMagick supports a much wider range of files, tends to be faster, and some assert that it produces higher quality files.

ImageMagick 6 was superseded by ImageMagick 7 nearly a decade ago. Version 6 is officially in legacy mode and while still technically supported (in a long term support sense) it generally receives only bug fixes – it fundamentally lacks many features, and most crucially it doesn’t support modern image formats correctly, such as AVIF¹.

Additionally, ImageMagick is a common source of serious security exploits. It’s very important to run the latest version (or very close to) at all times, to have as many critical bug fixes as possible.

Note that, depending on how you operate your WordPress site(s), you may or may not be seriously exposed to ImageMagick security problems. For simple single-author sites, where only the admin can upload anything to the site (images or otherwise), it’s arguably not a huge concern. But for more complex sites with multiple contributors – or worse, sites which accept images from general users or the public – using an outdated ImageMagick release is a serious risk.

Why isn’t this easy?

On some Linux distros, and when Plesk isn’t involved, it is easy – you just apt install imagemagick or yum install ImageMagick or at worst download the RPM and install that. Generally that installs ImageMagick 7 (and if not the very latest release, at least a recent one). You subsequently just run update on your package manager periodically and ImageMagick is kept reasonably up to date.

Ubuntu does not like ImageMagick 7, for some reason. No version of Ubuntu supports it officially, in the sense that it is not in any of the official package repos. If you apt install imagemagick, you’ll get version 6 – and not even a recent version 6, but 6.9.11-60 which is over three years old! That’s three years of well-known bugs – some of them potential security exploits.

So, unfortunately, the only way to install a modern version of ImageMagick on Ubuntu is manually.

Consequently, you have to manually install a suitable version of Imagick as well, and you have to do it into Plesk’s special PHP installation(s).

It took me several hours to figure all of this out, which is why I’ve written this post – so that nobody else ever has to.

The procedure

If you run into any issues, please let me know in the comments section at the bottom of the page. I endeavour to correct any mistakes, oversights, or confusion.

Note that most of these commands must be run as root. Either run them inside a root shell (e.g. su, or sudo bash) or prefix them with sudo.

Install ImageMagick 7

Fortunately, ImageMagick Easy Install (IMEI) exists to greatly simplify this step.

First, as a precaution IMEI insists you remove any existing ImageMagick installation(s). Manually installing a build of ImageMagick over the formally-packaged Ubuntu version could cause problems.

Next, download and install ImageMagick:

By default it’ll install a very recent version – usually the very latest release – but you can customise it if you wish with the --imagemagick-version argument to imei.sh.

Note: I had to use the --force argument to get imei.sh to actually build & install all the components – for some reason it skipped the dependent libraries (for AVIF & JXL support) and just installed ImageMagick, without AVIF and JXL support. Try it without first, since that’s supposed to be the happy path, but check that it says [OK] for every item; that nothing is [SKIPPED].

Once it’s completed successfully – which can take tens of minutes if you have a wimpy server such as is often used for WordPress hosting – double-check that you have a good version installed:

At time of writing that says 7.1.1-26 for me, but of course for you it’ll probably be something newer. You can consult ImageMagick’s download page to find out what the newest version is.

Install Imagick

First, download Imagick:

Next, you need to set the version string to the actual version – otherwise, at the very end of this process, you’ll find that WordPress quietly refuses to use ImageMagick / Imagick! Do that by editing the php_imagick.h file. You should see, somewhere near the top of the file, something like:

#define PHP_IMAGICK_VERSION    "@PACKAGE_VERSION@"
#define PHP_IMAGICK_EXTNUM     30700

You need to change that first string to the version declared on that second line. 30700 means version 3.7.0. So in my case I replaced "@PACKAGE_VERSION@" with "3.7.0".

Now you need to determine where the relevant PHP installation is – the version that Plesk is using to run WordPress for your website(s). You can find that out in various ways, perhaps the simplest being to log in to your Plesk dashboard, open the “Websites & Domains” section, and look at the PHP version listed for each website of interest.

In my case I’m using PHP 8.2. So now I know that the PHP install of interest is located at /opt/plesk/php/8.2/ (Plesk installs all its versions of PHP in /opt/plesk/php). I’ll use that in the subsequent commands shown here, but make sure to adjust that to suit whatever version of PHP you’re using.

To build Imagick, you need the PHP developer tools – for your particular Plesk PHP installation(s). e.g. in my case I’m using PHP 8.2, so I need to run:

Now you need to configure the Imagick build:

Don’t forget to change “8.2” to your version of PHP, if it’s different!

It should only take ten seconds or so to configure, build, & install Imagick.

Now, rename the built library so that Plesk updates won’t clobber it:

Lastly, although it’s technically optional, it’s nice to fix the permissions of the installed library:

Load Imagick into PHP

Annoyingly, PHP won’t automatically notice Imagick is installed – you have to tell it so, manually. Though this is pretty easy to do. There are a few ways to do it, the easiest being through Plesk: go to the “Tools & Settings” section of your Plesk dashboard, click “PHP Settings” (from the “General Settings” category), then click on the relevant handler in the list (e.g. “FPM application”). If you’re not sure which is relevant, look for a non-zero number in the “Domains” column.

Click on “php.ini” to switch to that tab, and you should see a text field containing the contents of the relevant php.ini file. Somewhere in this file – technically anywhere, but I like to scroll down to the section where all the other extensions are listed – you need to add the line:

extension=imagick_custom.so

Then, click the “OK” button to save your changes.

In theory Plesk will now restart the relevant server daemons, to have them pick up the change, but if you subsequently find that WordPress doesn’t seem to see the new ImageMagick installation (or you edited php.ini directly from the command line), you can give it a more forceful shove:

You should now be set – you can test your upgrade in a variety of ways, such as:

• Try uploading an image in a format, or using features such as animation or transparency, that wasn’t previously supported. e.g. AVIFs. Note that you might need additional WordPress plug-ins to enable use of the new formats, e.g. AVIF Support or any of the numerous SVG support plug-ins.
  
  See also my earlier post on my Image workflow for WordPress – particularly the section on AVIF.
• Check phpinfo – in your Plesk dashboard, go to your website(s) in the “Websites & Domains” section, click “PHP” (under the “Dev Tools” category), then click the subtle “View the phpinfo() page” link to the right of the first pop-up menus. Search for “imagick” – you should find an entry for it, with a table of plug-in information such as its version, the version of ImageMagick being used, and the file formats supported.

Addendum: updating ImageMagick & Magick

You can of course just repeat all the above steps to perform a fresh install, incorporating any updates since you last installed everything. But you can save a little time by keeping the imei and imagick folders around, and just doing:

1. git pull --rebase in each, then re-run their respective build commands. For Imagick you’ll probably have to git stash first, in order to do the git pull, and then restore your version string patch with git stash apply.
   
   Don’t forget to check if you need to update the version string in php_imagick.h.
2. Rename the built imagick.so again, and fix its permissions.
3. Restart the PHP daemon.

1. Some versions & builds nominally support AVIF, but this support is almost by accident – what they actually support formally is HEIF, for which they use libheif, which can be built with AVIF support as well, but in my experience that support is buggy and incomplete – e.g. alpha channels are not supported. ↩︎
2. Alas I don’t actually know if / how often it was successfully exploited, as far as Google saw. I have to imagine it was not uncommon, though, given the large attack surface that is ImageMagick’s APIs and image plug-ins, not to mention how lucrative a target Google is. ↩︎

WP Dark Mode had ‘flashing’ problems, though – where the page loads first in normal, ‘light’ mode and only then re-renders into dark mode. Possibly just a result of interference by WP Fastest Cache, which I later realised was probably deferring WP Dark Mode’s JavaScript files past initial page load. Irrespective, I found that Dracula Dark Mode worked better – though still not flawlessly in this regard – so I switched to that.

However, I eventually noticed that Dracula Dark Mode adds 415 KiB to every single page load, with its JavaScript and CSS files. That doubles the total size for some pages, even with WordPress & Jetpack bloating the baseline. Its own analytics suggested that basically nobody uses dark mode, at least amongst people that browse my website. So that does not seem like a reasonable trade-off.

Thus, with a bit of sadness, I’ve disabled the plug-in. Maybe in future the plug-in’s authors can find a way to optimise things such that its JS & CSS is only loaded if dark mode is actually in use.

Turns out, though, that almost no websites support dark mode anyway – I discovered as much while having dark mode enabled during my own testing. So it doesn’t seem like I’m an odd one out, and my tiny website is not going to start any trends. From the looks of it the way most people actually tackle the web in dark mode is through browser plug-ins which basically do the same thing as the WordPress plug-ins, but for every website. And only users actually interested in dark mode have to pay their price.

I haven’t tried any of them, but there’s numerous Safari plug-ins for dark mode, e.g. Dark Reader, Noir, Dark Mode for Safari, etc.

It does mean I can’t do image substitutions for dark mode users, but I couldn’t find any dark mode WordPress plug-in that works correctly in that regard anyway (they seem to do naive URL substitutions, without accounting for images having various replicas of different sizes per WordPress standard practice, and certainly without supporting Perfect Images). It’s also rare that I have a dark mode version of an image available – though I can at least be better about using actual alpha channels rather than fixed white backgrounds, going forward.

My input images generally fall into three categories:

1. Screenshots, as PNGs.
2. Random 3rd party images, typically as JPEGs but sometimes PNGs or other formats.
3. Photos, as Nikon NEFs.

Some of these formats can be published directly into WordPress – mainly PNG and JPEG – but not all, and neither PNG nor JPEG are the best file formats for anything these days. In terms of compression efficiency, there are numerous superior formats – JPEG 2000, JPEG XL, HEIF¹, WebP, AVIF, etc.

Using an appropriate and efficient format – and suitable compression quality settings – is important to me to save disk space, save bandwidth, minimise page load times, and ensure images are seen the way I want them to be (re. lossless vs lossy).

Best image codecs

Legacy options

PNG and JPEG are supported in practically any & every web browser still in real use today. As is GIF, technically, although it’s strictly inferior to PNG [for static images] and actual video formats [for moving images]. It certainly is possible to still use them, but it wastes storage space & bandwidth, and hurts page load times.

That said, PNG is not the worst option if you use appropriate tooling to maximise the compression. The level of compression you achieve ‘out of the box’ with most applications – e.g. Photoshop, Apple’s apps, etc – is actually quite poor. There are numerous specialised tools which can greatly improve the compression. I recommend ImageOptim – it’s free and open source. It typically reduces PNG files sizes by a further 20% to 50% (depending on how much fine detail or noise the image contains) without any loss of image quality. It actually makes PNG competitive with the modern formats to a degree, although ultimately still not the best.

It’s quite configurable, including with regard to stripping metadata or not – although, alas, it offers no nuance in this, such as keeping copyright metadata but removing spurious camera metadata, or geolocations.

It’s also possible to use such specialised tools for lossy PNG compression. PNG is not inherently lossy, but by manipulating the image before compression it is possible to greatly improve its compressibility. e.g. by reducing the colour palette, adding or removing dithering, or simply removing fine detail. Various tools – including ImageOptim – will do this for you if you wish, although be warned that the resulting image quality is unpredictable and sometimes very poor (exhibiting obvious colour changes, banding, or visual artefacts otherwise).

The example below is a fairly typical “good” result – the file size is cut by 70%, but the lossy PNG compression has introduced noticeable banding and dithering. You might consider it worth the trade-off but consider that a lossy WebP version, also saving 70% on file size, doesn’t have any noticeable image degradation. And an AVIF version with similar image quality cuts the file size by 80%. So while you might think it’s neat to use a ‘lossy’ PNG and get – by PNG standards – dramatically higher compression, you’re probably better off just using WebP or AVIF.

Non-options

Despite its age JPEG 2000 is surprisingly good in my experience – I used it many years ago on this website for my Raw converter comparison as an alternative to TIFF and PNG, as it yielded file sizes about half that of PNG. It’s competitive even with newer formats like WebP and AVIF. JPEG XL is purportedly even better again. Alas, no browser other than Safari supports either of them.

HEIF exists and is “modern” but isn’t really in the same ballpark – while it is better than JPEG, that’s a low bar; it achieves worse results even than JPEG 2000, a codec that’s twenty years older. Its only claim to any fame is that it’s the native source format for many photos today, thanks to its use on Apple iDevices. In any case, the only current-version web browser which supports it is Safari.

Viable options

The only modern format which is universally supported² is WebP.

AVIF is nearly universally supported, with the unfortunately notable exception of Edge.

I choose to use AVIF nonetheless, as my audience are unlikely to be using Edge anyway, since they’re unlikely to be using Windows at all. I also like to assume that Edge will, eventually, get with the program – although the fact that AVIF support was apparently incorporated in versions 114 to 117, but then removed, is concerning.

So those are the two options, basically. For better or worse, neither one is strictly superior to the other.

It is case-dependent and a little subjective as they have noticeably different methodologies:

• AVIF tends to be heavy-handed with ‘noise’ removal, which seems to be a significant part of how it achieves better compression.
• WebP will more faithfully preserve noise (and artefacts from earlier lossy compressions), which can be counter-productive.

AVIF really excels – compared to WebP and earlier codecs – with more aggressive compression settings. It’s much better under tight file size constraints. It also performs particularly well for images which aren’t so clean to begin with – where they do have some actual image noise, or visible compression artefacts from an earlier lossy compression stage, or otherwise fine details that aren’t important to preserve.

WebP behaves more “traditionally” – like JPEG – with regard to increase blockiness and banding as you crank up the compression. AVIF does a much better job of degrading image quality more ‘smoothly’ across the image – so that particularly bad, noticeable artefacts don’t develop as easily. Even while it preserves more genuine detail.

WebP is more competitive with high quality settings or high quality, ‘smooth’ images (e.g. screenshots or computer renderings). In lossless mode WebP universally outperforms AVIF, often by a significant margin. In fact even PNG typically outperforms AVIF for lossless compression!

I’ve also noticed that WebP is substantially better at compressing repetitive patterns (even if they’re not perfectly identical).

AVIF seems particularly good at reducing visible artefacts resulting from JPEG over-compression, and in avoiding prominent compression artefacts in general – such as in the example below, where the file sizes are very similar (14 KB for AVIF, 13 KB for WebP) but AVIF does more with it – preserving more genuine detail such as in the camera lens and IR sensor even while doing a better job of removing the JPEG artefacts (noise, blockiness, and banding).

While generally I avoid re-compressing from an already lossy source since it tends to just compound the compression artefacts, AVIF can be useful for replacing low-quality JPEGs when you don’t have a quality original available. It can actually improve subjective image quality – by correcting JPEG artefacts – even while substantially shrinking the file size.

Image format conversion

There’s basically two schools of thought on converting images to their serving format – do it in advance of uploading the image to WordPress, or have WordPress do it (via one or more plug-ins). I prefer the former as:

1. I have more control over the images by doing the conversion myself.
   • I can pick the best format for each situation.
   • I can customise compression settings to suit the situation (e.g. use more aggressive compression if the source image isn’t high quality to begin with) and use (e.g. use lossless for images which are about comparing image formats, RAW converters, or other such situations where viewers need to see the image exactly).
2. I have more reliably-available computing horsepower locally; I can run pretty much any conversion or optimisation process and it’ll just work. In contrast, WordPress-hosted processing is subject to various limits on runtime and RAM usage, which can cause things to fail in all sorts of ways both obvious and nefarious. Most web servers [used for WordPress sites] have way less RAM available than even an entry-level personal computer. Processing of “large” images, such as photos from a camera, will fail with default WordPress & PHP settings.
3. Every additional WordPress plug-in increases the possibility of problems, whether due to bugs in the plug-in, the possibility of incompatibilities between plug-ins, etc.
4. WordPress plug-ins don’t always age well; each one I adopt is yet another plug-in which I might have to migrate off of in future.
5. WordPress plug-ins for image format conversion & optimisation tend, in my experience, to be both buggy and money-grubbing. Many are tied to 3rd party services like CDNs or “Cloud”-based image processing, and try to lock you into pricey and unnecessary paid subscriptions.

Nominally having WordPress do it means you can just upload any random image without care for its format or compression, and that over time you can easily adopt new image formats just by installing new plug-ins, with all existing images converted retroactively. In reality, new image formats come along very rarely and popular ones – like PNG, JPEG and WebP – are supported basically forever.

You do have to be a little careful, however, to not over-compress your original uploads (or, retain higher-quality versions locally). Especially if you’re churning through image conversions & uploads rapidly, you might not immediately notice compression artefacts. Having the original available in order to redo the compression is valuable.

Advance conversion

There’s a further choice as to whether you do the processing locally or use a website. I prefer to just do it locally, for some of the same reasons as not using WordPress, and also because in my experience I can achieve better results – websites that do image conversion / recompression, especially those that do it for free, use weak compression in order to minimise processing time, and consequently do not achieve the best results.

The best tool I’ve found for local image processing is Image Tool+. It supports all the formats you’ll likely need and is designed for easy batch conversions.

In years gone by I used GraphicConverter, but it doesn’t support AVIF.

It’s important to note that the PNG files produced by Image Tool+ are not very efficiently compressed – you should run them through ImageOptim if you actually intend to use them.

Publishing images in WordPress

WordPress supports some image formats natively, and does a passable job of handling them by default. So you don’t have to do anything additional, necessarily. However, there’s several plug-ins I recommend which significantly improve its capabilities.

AVIF Support

As it says on the tin, it adds support for AVIF to WordPress, which sadly lacks support otherwise. Without this plug-in, WordPress will simply refuse to accept AVIF uploads.

It’s free, open source, and works pretty seamlessly, as long as your web server and WordPress installation are sufficiently modern. The easiest way to determine if that’s the case it to simply install the plug-in – its Settings page will tell you if AVIF is supported or not. If it’s not, only then will you need to do some package upgrading. In particular, you need (as best I can tell from experience and what I’ve read online):

• PHP 8.2 (or later).
• libavif and suitably-compiled versions of GD and PHP.
• ImageMagick 7.0.25 (or later)
  
  …or ImageMagick 6 with a suitably new and compiled libheif w/ AVIF support. I haven’t been able to pin down specific version numbers, and it might vary by package repo (as libheif has to be compiled with certain flags to include the AVIF support). In a nutshell you can tell if your system has it by following the dependency graph from your libmagickcore-6… library (via apt info <package> or similar) and seeing if it includes libheifN with in turn an [installed] dependency on svt-av1 or libaomN. Where ‘N’ may be any number.
  
  Note: ImageMagick 6 doesn’t support alpha channels in AVIF images (see Bug: Alpha channels, below). So use ImageMagick 7 if possible.

Even though all those versions are quite old, I actually had to switch web hosts in order to get them, as you’d be sadly surprised how many WordPress hosting services are running wildly ancient versions of Linux (kernel & distro) and PHP. Now that I have my own Linux VPS, however, it was quite trivial – I basically just used apt and Plesk to install the latest versions of all the relevant software (which you should be frequently doing anyway, for security patches and bug fixes). Although sadly that still only gets me ImageMagick 6 (and an outdated GD that doesn’t support AVIF) – Plesk PHP builds are pretty far behind, and Ubuntu doesn’t officially support ImageMagick 7 at all! 😠

Note that you only need one of GD or ImageMagick to have the necessary AVIF support, which is fortunate in case one of the two is difficult to upgrade with your particular system (such as if you use Plesk).

ImageMagick is apparently superior:

It’s recommended though to use Imagick lib. It gives way better results in terms of speed, quality and size.

AVIF Support author (GrandPlugins)

I haven’t tested that claim myself, but you’ll find it repeated in numerous places online, and not just in the context of AVIF. It sounds like the common wisdom is that GD just isn’t very good³.

Bug: AVIF over-compression

At time of writing, it has a bug whereby it doesn’t respect image quality settings, neither the WordPress defaults nor any customisation you might do with other plug-ins. Instead, it always uses a 30% quality setting for AVIF compression (e.g. for thumbnails) which often results in noticeable visual artefacts from the over-compression. I’ve reported this to the developer and 🤞 they address this soon, as it looks like a trivial one-line patch.

Update: the plug-in author fixed this in version 1.0.5, January 2nd 2024. As a bonus they also added plug-in settings for specifying the desired image quality and (for GD) ‘speed’ (how hard the AVIF encoder tries, trading off compression speed for effectiveness).

Bug: Alpha channels

AVIFs with alpha channels don’t work with ImageMagick 6, at time of writing – any time WordPress re-encodes the image, such as for thumbnail generation, it removes the alpha channel. Typically this results in the transparent sections turning black instead.

For now, I use WebP when transparency is involved, as I’m hamstrung by Plesk’s lack of support for ImageMagick 7 in their PHP packages. 😕

I ultimately upgraded to ImageMagick 7 to fix this bug. See my upgrade guide if you’re on Ubuntu or using Plesk, or otherwise can’t seem to get ImageMagick 7 from your normal package management process.

CDN incompatibility

Note that some CDNs still don’t support AVIF, and there’s nothing the AVIF Support plug-in can do about that. You might be using such a CDN without even realising it – e.g. the popular Jetpack plug-in secretly uses the wp.com CDN, so AVIF images don’t work in some places, such as Jetpack’s “Related posts” feature. Alas there’s not much you can do other than not use such broken CDNs – nor plug-ins that rely on them, like Jetpack.

In general you don’t want to use such CDNs anyway, because their lack of support for AVIF – or any other content format – is usually only a result of them mucking with your images in some way. Not all CDNs are bad, though – e.g. Cloudflare has no issues with AVIF because they don’t try to mess with your files.

Enable Media Replace

This lets you replace an existing image without breaking any use of it in existing posts, pages, etc. Including with a different file format. That latter detail is something most competing image replacement plug-ins do not support [reliably], but it’s crucial if you want to upgrade any existing images on your website.

It’s free and open source.

Image Regenerate & Select Crop

This lets you perform a bunch of helpful little things, including:

• You can define custom image “thumbnail” sizes (and modify WordPress’s defaults), which can be handy for tailoring your images to your actual presentation sizes. The WordPress defaults are pretty arbitrary and typically don’t match what your theme desires, let-alone any other plug-ins’ needs (such as for galleries, slideshows, etc).
• You can adjust the default image compression quality setting (for each thumbnail size individually).
  
  Note however that this doesn’t always apply, e.g. currently the AVIF Support plug-in has a bug whereby it ignores this setting. The setting seems to work for the built-in-supported image formats, though, like JPEG and WebP.
• You can manually delete or [re]generate thumbnails in each of the possible sizes, for images both individually or en masse. This can be handy if you change relevant settings (like compression quality, above) or in debugging situations (such as if you’re experimenting with other image plug-ins and they muck up your thumbnails).

It’s free (albeit with optional paid ‘advanced’ features).

Perfect Images

It’s baffling that to this day WordPress doesn’t support modern displays – and I use ‘modern’ in a very liberal sense, since we’re talking circa 2010 onwards. That is, displays designed with a high pixel density that use a non-1-to-1 ratio of points to pixels. i.e. any smartphone or quality computer display in the last decade.

The result is images that render at a quarter (or worse) of full resolution, looking pixelated or soft.

If you care enough about image quality to even consider what image formats or compression settings you’re using, you absolutely should be using Perfect Images.

Basically it fixes & extends WordPress’s image support to – mostly automagically and invisibly – just work with full-resolution images. It’s particularly noticeable and essential for things like screenshots, or any images containing text, as those are especially obvious if rendered incorrectly.

Its core functionality is free – and you can get a fair way with just the free version – but the pro version is worth it, even if a bit pricey.

Usage tips

Fix WordPress’s image size limit

Make sure to check the “Image Threshold … Disable” checkbox in the General settings. This fixes a truly obnoxious WordPress bug whereby it mangles uploads of large images.

Upload ‘Retina’ images specially

For images which are explicitly “2x” – such as screenshots – it’s important to upload them ‘manually’ using Media > Add New Media File, as opposed to e.g. just drag-and-dropping them into a post. The plug-in adds an “Upload New Retina Image” option to the dedicated upload page, which registers the uploaded image with WordPress at technically a quarter of its actual size. That basically tricks WordPress into using the correct dimensions for the image – otherwise, WordPress mistakes the pixel dimensions for the point dimensions, and will naively try to display the image at four times its natural size.

Don’t worry, Perfect Images preserves the real, full-resolution version as the “2x” version of the upload, and will display that instead to your visitors.

This particular upload method is the only way to get images to render correctly in all cases. In some places – e.g. embedded in posts – you can manually specify the correct image dimensions, but that’s both tedious and error-prone, and not possible in all uses.

The only caveat is that those images will look ugly and blurry in the post & page editors. Don’t worry, they’ll render correctly in the actual published (and preview) version of your posts & pages.

For images which don’t have an intrinsic pixel density – such as photos – you typically don’t have to worry about this, as you’ll usually just let them render at whatever size the viewport & layout permit, up to their natural full size.

Limitations

The core functionality works reliably in my experience (over many years now), but some of the peripheral features are broken or notably buggy:

• Image replacement will not work correctly if the file format changes – and it won’t even recognise this case and prevent it, instead leaving you with broken images. Use Enable Media Replace for this instead.
• Batch regeneration of thumbnails doesn’t work reliably – it will silently fail midway if an error occurs, such as it encountering a video file. Use Image Regenerate & Select Crop for this instead.
• Custom Image Sizes don’t work correctly – they always force cropping of the image (“resize to fill”), rather than resizing to fit. This is almost never what you want. Use Image Regenerate & Select Crop for this instead.
• For the Pro version [only], auto-update doesn’t work. You have to periodically check the website for new versions.
• It sometimes reports “issues” for images, in its special dashboard under the Media section, when there aren’t any. This is of course pretty insignificant – you can just ignore it – although it might hide any actual issues if they occur. I did find a way to clear these bogus issues, but it involved manually deleting all thumbnails for all my images and regenerating them, which was a bit of an ordeal due to other, aforementioned bugs. So I don’t recommend mucking with it.

1. Note that HEIF does support lossless encoding but support for this amongst actual encoding applications is poor to non-existent. As such it’s generally not a suitable replacement for PNG in practice. ↩︎
2. As the matrix shows, no version of Internet Explorer supports WebP. But – though there apparently is some non-trivial number of people still using it – I don’t consider Internet Explorer a browser of concern anymore, given it has an official and straightforward successor in Edge, and its last version was released a decade ago in 2013. ↩︎
3. Although for image compression, specifically, this is odd, since there’s only a couple of underlying libraries they could possibly be using, and while they do vary significantly in speed they should produce very similar outputs. ↩︎

The built-in “code” block for WordPress (the CMS I use for this site) is virtually useless – it’s just a <pre> block, essentially.

The appearance may vary depending on WordPress theme, but will virtually always be bland.

In fact, it’s not even guaranteed to use a monospaced font – the example I’ve shown here is what you’ll probably get with any given WordPress theme, but it’s not actually the default for the theme I use (GeneratePress) due to a known bug in GeneratePress (which the theme authors outright refuse to fix!).

In any case, you have to use WordPress plug-ins to extend or replace it with something that actually looks in any way decent.

Unfortunately, Swift is a complicated language, even just at the “superficial” level of syntax highlighting. And most generally-popular syntax highlighting tools are both:

1. Focused on languages like JavaScript and HTML, not Swift.
2. Written in JavaScript or Ruby, with no access to standard tooling like the Swift Language Server Protocol.

Since I’m using WordPress for this site, Ruby’s not a good option (and I didn’t find any relevant WordPress plug-ins which rely on it, anyway). Hypothetically I could add a Ruby environment to my server and do static generation through it, but, ugh. It’s annoying enough dealing with JavaScript and PHP. If you’re going to go to that much trouble, you’d probably be better off actually using Swift (e.g. SwiftSyntax). And while I’d welcome a WordPress plug-in which does exactly that, alas no such plug-in exists today.

So, I spent way too much of my time trying out a bunch of the available WordPress plug-ins, and now I shall report the results so others don’t have to suffer [as much].

I’ve presented previews for both light and dark modes (but my apologies to dark-mode viewers that all the samples default to light mode – an unfortunate limitation of my CMS).

Baseline: Xcode

Syntax highlighting theming is a very subjective and somewhat personal preference. I really must stress this, as something to keep in mind as I critique these plug-ins based on my preference, which is pretty close to Xcode’s default theme.

I’ve tried to focus mostly on how well the plug-ins understand Swift syntax & grammar and what functionality they offer broadly, rather than which ones look prettier out of the box. Most have at least some degree of custom theming support, or at least permit unofficial theming through straightforward CSS overrides.

It is unsurprising that Xcode does by far the best job of understanding and correctly syntax-highlighting Swift code, of anything tested here. It has the advantage of being able to actually compile and analyse the code with full context – the example shown here has supporting type and function definitions “off-screen” – which WordPress plug-ins do not¹. While I set out on this exploration hoping to find something effectively as good as Xcode, I wasn’t really expecting to (and spoiler: I did not).

Allow me to call out a particular few things Xcode does right, that (as you’ll see) few if any of the WordPress plug-ins do:

• In short, it supports all Swift syntax. It correctly identifies all the keywords (and things that are not keywords but happen to be the same word, such as static properties called default as in the example code).
• It utilises not just colour but font and font weight. This permits it to effectively delineate things without having to use an excessive variety of hues.
  
  Some might finds its results comparatively bland with the default theme as shown here, in light mode especially, but it has other themes for those that want a more hue-centric approach, and supports a very good degree of theme customisation.
  
  The default theme doesn’t “demo” well (in light mode), in the same way that colour-accurate TVs look rather bland and unattractive in the showroom but are actually great in real-world use in your home.
• Even though it uses multiple font weights, it still preserves correct letter spacing.
• It understands DocC’s limited Markdown-like markup within documentation comments (and can even render them as properly styled text, although that’s not shown here).

I’ll also call out one thing which – in my opinion – it gets wrong, which is essentially not recognising custom type names. It renders them as plain text – no highlighting at all – yet gives special treatment to “built-in” types (from the Swift standard library) like String. It’s fine if it wants to distinguish between those two sets of type names, but it should use some kind of highlighting for both of them. Many of the WordPress plug-ins actually do a better job in this respect.

Common limitation: no Light/Dark mode support

One thing that none of these plug-ins do, that you would think they could and reasonably should, is explicitly support light / dark mode – even though most include both light and dark themes (some plug-ins even include light and dark variations of the same theme – so close!).

Instead, you have to pick just one theme. Furthermore, if you want proper light and dark mode support you have to pick a light theme specifically, to match WordPress’s default mode of light. This limits your control over the appearance in dark mode – and may make it difficult for you to find a theme which suits your aesthetic preferences in both modes.

WordPress itself doesn’t support light/dark mode – you have to² use 3rd-party plug-ins. Depending on which one you use, you might get viable automatic switching anyway. The several that I experimented with were all able to make my theme adapt actually quite well.

I initially used WP Dark Mode, but discovered it was buggy in that it would load pages in light mode first and only after the initial render would it switch them to dark, making browsing my site in dark mode very uncomfortable. It also didn’t work properly with SyntaxHighlighter Evolved. I consequently switched to Dracula Dark Mode which is a very similar plug-in but doesn’t have those bugs.

Note that most of the dark-mode screenshots shown here were taken while using WP Dark Mode. There may be slight differences in colours with Dracula Dark Mode (or some other dark mode plug-in), but in my brief experimentation the results are virtually indistinguishable.

The contestants

Code Block Pro

This advertises itself as using the syntax highlighting engine from Visual Studio Code, but that’s actually misleading – it uses Shiki, which is really its own engine albeit one that utilises the same TextMate-inspired grammar definitions and themes as does Visual Studio Code.

It’s open source and free for the most part – for a token $12 you can support the author and obtain a couple of dozen extra themes, adding to the two dozen or so that it includes by default.

Performance

If you’re familiar with Visual Studio Code for Swift development, then you basically already know how it performs, as the results are (in my testing) identical.

That’s only mostly a compliment, though. This plug-in, like Visual Studio Code, doesn’t really understand Swift, it merely does a relatively good job of faking it.

Unlike every other plug-in tested, where the grammar parsing is completely independent of the theming, the performance of this plug-in does vary between themes. Thus, some themes might have colours you hate yet be the only ones that actually identify Swift keywords correctly, while others are the reverse. This is demonstrated in the example shown here – the Light Plus theme – where the colours are the least ugly of the themes available but it doesn’t recognise some basic Swift syntax, like protocol conformances, which is recognised in other – albeit uglier – themes.

But, in general, it:

• Actually understands the difference between function parameter labels, parameter names, and parameter types.
• Tends not to recognise custom type names, only the Swift stdlib & Foundation ones (e.g. notice it doesn’t recognise Floor but does recognise String). This is somewhat common behaviour amongst the plug-ins tested (and Xcode itself).
• Doesn’t recognise some important keywords, such as async and some.
  
  As it happens, this is because the Swift grammar file it uses is quite a few years old and seems like it might be largely abandoned (other than sporadic community updates such as this which might or might not be incorporated by this plug-in). This is the same grammar file that Visual Studio Code uses, making it doubly-surprising, but I guess it says a lot about the level of interest the Visual Studio Code community has in Swift.
• Is not easily fooled by the use of ambiguous names, e.g. the default static property of HomeItem that’s often mistaken for the default keyword by other plug-ins.

Pros

• Includes the ability to highlight an arbitrary set of lines by blurring out all the others (but readers can mouse over the code block to unblur everything, if they want to see the full context of what you’re highlighting). This particular approach – blurring rather than just using a different background colour – is unique amongst all the plug-ins I found, and aesthetically far superior. Most of the other plug-ins don’t even have a way to highlight or hide certain lines.
• Uses server-side rendering with CSS inlined into the HTML, so code is highlighted right from page load without delays or visual glitches.
  
  Some other plug-ins tested here do server-side syntax analysis too, but to actually effect styling they use class tagging of HTML spans with CSS, which can mean rendering glitches if the CSS takes a while to load and the browser renders the code without it in the interim. Code Block Pro avoids that (and might also play better with other styling plug-ins or modifications, such as dark mode plug-ins).
• Has a live playground so you can easily test it out (although that playground is hard-coded to use the Fira Code font, which is only one of a number of open-source font options it provides).

Cons

• No global settings – if you decide to change any settings, such as the theme, at any point, you have to manually find and adjust every existing code snippet manually.
  
  This might be considered a positive by some users, where they want existing content to remain as-is. However, some plug-ins offer both a global setting and the ability to override that on a per-case basis, providing more flexibility.
• The provided themes – even with the paid expansion pack – are predominately intended only for dark mode, and most of the light mode ones are pastel. So if you want a clean light mode theme, as I do, you have only about three options with this plug-in.
  
  Furthermore, the performance varies between themes, as – unlike every other plug-in tested here – the themes are in essence tied into the parsing.
  
  None of the provided themes really do Swift justice compared to how well they work for other languages. Especially within the limited selection of light-mode themes, there’s precious few that don’t make obvious mistakes (like conflating the some keyword with operators, or being confounded by generics syntax).
• Theme customisation options are extremely limited, not just officially but even unofficially with custom CSS. Although, the author seems receptive to theme suggestions – to add to the paid expansion pack – if you find something you like in the Visual Studio Code Marketplace.
  • The only way it officially allows any custom theming is with an unusual mechanism documented only in a tangential GitHub discussion: you select the theme called “Use CSS Variables”, which is a ‘theme’ that merely specifies var(--xyz) values for the color CSS property. You’re then expected to specify values for those CSS variables in some suitable stylesheet (which the plug-in does not facilitate).
    
    This custom theming functionality is only available in the paid version.
  • It only officially supports adjusting the colours – you nominally don’t have the ability to adjust font families, sizes, weights, or styles.
    
    It is possible to match each type of element, but it’s pretty clumsy and fragile, because…
  • As mentioned under Pros, it inlines the style information directly into the HTML span tags, as simple color style attributes. While that’s good for avoiding rendering glitches, the downsides are that:
    • It produces more verbose HTML than if it just used a short class name on the spans (as all the other plug-ins do), which can hurt page load times.
    • It’s more difficult to customise the styling with CSS, since you have to match on the colours – using CSS attribute queries like span[style*=#xxyyzz] – which is not just awkward but can be impossible to do precisely for multiple distinct grammar elements depending on the base theme used.
    • It optimises the HTML by merging (server-side) span elements with the same style information. That’s great for reducing page size and load times, but if the base theme doesn’t already visually distinguish between two distinct grammar elements, it’s impossible to distinguish them through custom CSS.
• Custom themes don’t render in the post editor – you just get plain pre-formatted text. (built-in themes work fine in the editor)
• Uses a custom Gutenberg block type, rather than just extending the standard Code block. So you can’t just upgrade your whole existing site – you have to manually go through and find every existing Code block, and manually migrate each one.
  
  Inversely it’ll also be more difficult to migrate away from, if you choose to do that some day, as you’ll likely have to repeat that whole process no matter what replacement plug-in you choose.
• If you enable the ‘Copy’ button for the convenience of your readers, it includes a duplicate copy of the code in a hidden span (as do at least some of the other plug-ins tested, although I didn’t always call it out here).

So in a nutshell, if you’re completely happy with its built-in theme options, then this is one of your better options. But if you want theme customisation, it becomes worse than many of the other plug-ins, sadly.

CodeColorer

A very old – though nominally still maintained – plug-in uniquely based on GeSHi.

It’s open source and free (as is the GeSHi engine underneath it).

Neither the plug-in itself nor the GeSHi engine have seen a lot of activity in recent years (and confusingly the old GeSHi webpage is still up as is the early GeSHi page on SourceForge, creating an even worse first impression). Both predate the [public] existence of Swift entirely.

To be honest I’m including it here only for completeness. It basically doesn’t work – especially for Swift – and shouldn’t actually be considered. It seems intended solely for use via shortcodes – even though it does take over all existing <code> blocks – which I didn’t test as the use of shortcodes in WordPress is archaic, and poorly supported in the modern (Gutenberg) editor. They seem to still be officially supported, and not formally deprecated, but I think introducing any new reliance on them at this point is foolish.

Performance

So, yeah… no syntax highlighting at all. It’s not apparent to me if this is a failure specific to Swift or if the plug-in in general just doesn’t work. It does offer a [non-live] preview in its settings, which does work for its example snippet of JavaScript.

It also (by default) forces the code into a tiny box, although you can fix this through its settings.

There’s no per-use customisation since it just takes over any existing <code> blocks, and there’s very few global settings – including an absence of any setting for a default language.

I won’t bother trying to enumerate its specific pros and cons – it’s clearly not a viable contender.

Code Syntax Block

A simple plug-in based on Prism.js, with very limited customisation options.

It’s open source and free (as is the Prism.js engine underneath it).

Performance

Prism.js prides itself on being [relatively] small. Perhaps because of that goal of being “lightweight”, its performance is a bit mediocre.

The default theme makes it look even worse than it really is, because it bizarrely doesn’t provide any distinguishing styling for important things, like type names.

On the upside, it does get a few things right which other plug-ins often don’t – even others which also use Prism.js, curiously, like Highlighting Code Block. Things like it:

• Recognises @-attributes, such as macro and property wrapper invocations.
• Recognises relatively new Swift keywords such as async & await.
• Understands multi-line and raw strings.

On the downside it:

• Doesn’t recognise a lot of very basic Swift syntax – or, at least, doesn’t distinguish them with a span and therefore resigns them to the default, plain text styling of the overall code block – including but not limited to:
  • Variable names (neither their declaration nor references to them).
  • Function parameter labels & names.
  • Property names.
  • Tuple field labels.
• Doesn’t recognise method calls consistently (e.g. pack & reduce vs map in the example shown).

Although you can’t tell with its default theme, it actually recognises custom type names (although doesn’t distinguish them from Swift standard library types, like Xcode – though it’s debatable whether that’s a feature).

It uses font weight, not just colour, which would go a long way towards giving it higher fidelity without making it look garish if it didn’t use it really weirdly. Instead of bolding keywords, for example, it bolds function & method names – sometimes, when it recognises them correctly.

At least it defaults to Menlo, which is actually a respectable choice and makes it one of the few plug-ins tested that have a decent default for Apple platforms. In case you’re unfamiliar, Menlo was the default monospace font for Snow Leopard through Yosemite (before it was replaced by SF Mono). You’d most likely have encountered it in Terminal or Xcode, if you used a Mac in that timeframe (2009 – 2015). It’s still available on every Apple device (as of time of writing, December 2023).

Pros

• Extends the built-in, standard Code block. This makes it comparatively trivial to adopt if you’ve already got Code blocks on your website (although you may still need to go through and customise some things, such as the language in case auto-detection doesn’t work correctly).
  
  This also makes it easier to switch syntax-highlighting plug-ins, provided that the one you switch from or to also supports the standard Code block, which is sadly a minority of them.

Cons

• Hasn’t been updated in a year – possibly abandoned.
• Does everything client-side, so there’s a noticeable delay before syntax highlighting is actually applied (especially on first load, when the relevant JavaScript & CSS isn’t cached in the browser). It’s a bit visually jarring as the unstyled code is replaced with the styled.
• Adds its Prism CSS & JavaScript files to every page load, irrespective of whether the page actually needs them or not. This is the core Prism.js library only – the grammar file for each language is only loaded when actually needed.
  
  They are somewhat small files, at least – most of it is Prism.js at 30 KB alone, plus a few extra KBs for the chosen theme’s CSS. With Brotli compression they’re ~13 KB. Language grammar files tend to be only 3 KB or less.
• Very few built-in themes – only four – and using a custom theme is technically possible but awkward. The official instructions didn’t work for me, either – I had to use the WPCode plug-in to execute the relevant PHP:
  
  add_filter('mkaz_prism_css_url', function() {
    return '/wp-content/themes/prism-xcode.css';
});
• Theming is controlled globally with no ability to override it for specific uses.
  
  This is (IMO) better than not having any global controls at all, as with some plug-ins, but it can be problematic if you use more than one language in these code blocks across your website, as you might prefer different themes for different languages.
  
  You can technically work around this limitation using custom CSS, since the language is included as a class on the relevant pre and code HTML elements.
• Doesn’t render the syntax highlighting in the Gutenberg editor, so you’re stuck with the generic pre appearance there.

Enlighter

The official WordPress plug-in for the EnlighterJS engine.

It’s open source and free (as is the EnlighterJS engine underneath it).

Performance

Generally it does a poor job, with Swift code, and it’s not really a mystery why – its grammar file for Swift is especially spartan and hasn’t been updated since it was created over five years ago! That’s the Swift 4.1 era at best.

It actually behaves very similarly to the SyntaxHighlighter Evolved plug-in, but with the significant difference that it leaves things it doesn’t understand as the plain text colour (e.g. black in Light mode), so it’s much more apparent even at a glance that it doesn’t really understand much.

For example, it:

• Doesn’t understand @-attributes, such as macro and property wrapper invocations.
• Has no idea about the difference between function parameter labels and parameter arguments.
• Doesn’t consistently recognise references to properties, such as when they’re part of KeyPaths.
• Doesn’t understand some important keywords, like async, await, Never, etc.
• Recognises only a limited selection of types – all from the Swift standard library – and has no idea about custom types.
• Doesn’t recognise method calls consistently (e.g. pack & reduce vs map in the example shown).

In a nutshell, it’s doing little more than picking out a pre-defined list of keywords, identifying string & numeric literals, and comments.

Though it does at least handle multi-line and raw strings correctly (albeit only in some themes – in a few it underlines strings and mistakes the indentation as part of the string, for multi-line strings).

The choice of Courier New as the default font is… brave. It’s not actually its preferred default – it favours Source Code Pro foremost, with Liberation Mono as a second choice. They’re both reasonable open-source monospace fonts, but neither are standard fonts on any Apple devices, and the plug-in doesn’t include them.

You can customise the font to a very limited degree – the plug-in provides only five options, none of which are standard Apple OS fonts so the choice is effectively pointless. Thankfully you can override its font choices, like pretty much all its styling, with custom CSS.

Pros

• Supports both a global theme setting as well as use-specific overrides.
• Supports both soft & hard wrapping (the latter meaning it uses a horizontal scroller if necessary, rather than fitting the text to the viewport – generally not what I recommend since it’s pretty hostile to small screens but it’s a notable feature to make this behaviour configurable).
• Includes a pretty extensive theme customiser, as an actual HTML forms-style interface in the plug-in settings pages. That GUI is ultimately just a bespoke configurator for the CSS – which helpfully it also provides, in case you want to save or serve that elsewhere.
  
  And if that proves insufficient – or you just prefer to do it manually – it uses a sensible system of spans with suitable classes, so it’s easy to write custom CSS for styling.
• Provides its own Gutenberg block, but can also optionally be applied to the built-in WordPress Code block, as well as potentially blocks from other plug-ins (Crayon Syntax Highlighter & CodeColorer are explicitly supported – unclear if it also supports Urvanov Syntax Highlighter, the ‘reincarnation’ of the otherwise abandoned Crayon Syntax Highlighter).

Cons

• Built-in themes are pretty limited and (IMO) pretty ugly, at least for the light-style ones (which is ten of the thirteen). The one demonstrated here is the default – just called “Enlighter” – which is about the best it has to offer. 😕
• Puts its settings item at the top level of the WordPress admin menu, rather than under Settings.
• Adds its CSS & JavaScript files to every page load, irrespective of whether the page actually uses the Enlighter block or not. Along with some inline JavaScript in every page header.
  
  And they’re not trivial files, either. The CSS is 80 KB uncompressed – ~10 KB with Brotli compression, larger with GZip or Zip (Deflate). That’s factoring in CSS minification, too. The JavaScript is 63 KB uncompressed (~19 KB with Brotli).
  
  It does offer an option to supposedly avoid this – “Dynamic Resource Invocation” – but it’s disabled by default, and still requires inclusion of a “small” 1 KB JavaScript file with every page load just to determine if the rest of the code & CSS should be loaded. So, kind of a hack to try to cover up a design flaw. Alternatively, you can disable automatic inclusion of the CSS & JavaScript files and handle that manually, but I can’t imagine anyone actually wants to have to deal with that.
• Doesn’t render the syntax highlighting in the Gutenberg editor, so you’re stuck with the generic pre appearance there.

So, overall a pretty poor option, both in terms of how well it understands Swift – i.e. particularly badly – and how it looks out of the box. It does have a lot more options than most of the other plug-ins, and its GUI for theme editing might be a unique selling point for a – presumably rather limited – market of people that want to include Swift code on their website but aren’t comfortable writing CSS. Even that withstanding for argument’s sake, I think it falls solidly towards the bottom of the pile.

Highlighting Code Block

A relatively simple plug-in based on Prism.js, with limited customisation options.

It’s open source and free (as is the Prism.js engine underneath it).

Performance

Prism.js prides itself on being [relatively] small. Perhaps because of that goal of being “lightweight”, its performance is pretty poor – and pretty obviously so even at just a glance.

For example, it:

• Doesn’t understand @-attributes, such as macro and property wrapper invocations.
• Has no idea about the difference between function parameter labels and parameter arguments.
• Doesn’t consistently recognise references to properties, such as when they’re part of KeyPaths.
• Doesn’t understand some important keywords, like async & await.
• Doesn’t recognise method calls consistently (e.g. pack & reduce vs map in the example shown).
• Doesn’t understand multi-line nor raw strings.

On the positive side, it actually recognises custom type names (although doesn’t distinguish them from Swift standard library types, like Xcode – though it’s debatable whether that’s a feature).

It uses italics, not just colour, which goes a long way towards giving it higher fidelity without making it look garish. Unfortunately, its use of italics is weirdly inconsistent – e.g. it italicises some keywords but not all (e.g. final vs class), and italicises some type names but not others (e.g. VStack vs Image & Text).

It doesn’t take much effort to understand why – it’s using a very simplistic parser that knows virtually nothing about the language (other than a hard-coded list of keywords) and instead is just going off of capitalisation, mostly. Which is somewhat clever, and gets it a long way for such a simple method, but ultimately results in poor performance.

At least it defaults to Menlo, which is actually a respectable choice and makes it one of the few plug-ins tested that have a decent default for Apple platforms. In case you’re unfamiliar, Menlo was the default monospace font for Snow Leopard through Yosemite (before it was replaced by SF Mono). You’d most likely have encountered it in Terminal or Xcode, if you used a Mac in that timeframe (2009 – 2015). It’s still available on every Apple device (as of time of writing, December 2023).

It’s a bit weird that the performance is significantly different from some other Prism.js-based plug-ins, like Code Syntax Block. It’d be explicable if one plug-in were strictly superior to the other – suggesting simply use of a newer version of Prism.js by one than the other – but it’s actually a weird mix of improvements and regressions.

Pros

• Good bang-for-your-buck configuration options, which is to say that it has relatively few but it includes the essentials and with maximum flexibility (e.g. font customisation is by entering the actual font-family CSS string, rather than being limited to do a predefined short list of options as with most other plug-ins).

Cons

• Does everything client-side, so there’s a noticeable delay before syntax highlighting is actually applied (especially on first load, when the relevant JavaScript & CSS isn’t cached in the browser). It’s a bit visually jarring as the unstyled code is replaced with the styled.
• Adds its CSS & JavaScript files to every page load, plus some inline CSS & JavaScript, irrespective of whether the page actually needs it or not. This includes the entire Prism.js library with grammar parsers for every supported language, irrespective of which ones are actually used.
  
  And they’re not entirely trivial files, either – mainly because of Prism.js at 35 KB alone. Overall they’re 41 KB before compression (~18 KB with Brotli).
• Limited theming control – it has an unnamed built-in default, which you can override by specifying a server-side path to a custom CSS file (although functionally this isn’t much different from just putting your custom CSS in your website’s general custom CSS file, because of the aforementioned flaw whereby this plug-in inserts its CSS into every page load).
• Theming is controlled globally with no ability to override it for specific uses.
  
  This is (IMO) better than not having any global controls at all, as with some plug-ins, but it can be problematic if you use more than one language in these code blocks across your website, as you might prefer different themes for different languages.
  
  You can technically work around this limitation using custom CSS, since the language is included as a class on the relevant pre and code HTML elements.
• Includes support for a relatively small number of languages (by default), although that does include Swift and Objective-C, among many other popular languages. I list this as ‘con’ only in a relative sense – for most users its built-in shortlist is likely quite sufficient.
  
  You can provide a custom build of Prism.js if you need others, although it’s left as an exercise to the user to figure out how to do that (and to then maintain it).
• Doesn’t render the syntax highlighting in the Gutenberg editor, so you’re stuck with the generic pre appearance there.
• Uses a custom Gutenberg block type, rather than just extending the standard Code block. So you can’t just upgrade your whole existing site – you have to manually go through and find every existing Code block, and manually migrate each one.
  
  Inversely it’ll also be more difficult to migrate away from, if you choose to do that some day, as you’ll likely have to repeat that whole process no matter what replacement plug-in you choose.

Prismatic

A uniquely versatile plug-in that supports both the Prism.js and highlight.js engines.

It’s open source and free (as are the Prism.js and highlight.js engines underneath it).

Unfortunately, it immediately disqualified itself by simply not working. After installing & activating it in WordPress, nothing happens. The built-in Code block doesn’t change, there is no new Gutenberg block (contrary to its documentation which claims it adds a “Prismatic” block), and nothing appears anywhere in the WordPress Admin menu, such as a global settings page.

I checked the PHP logs and found no mention of the plug-in nor any relevant log messages.

It’s unusual – in my experience – for a WordPress plug-in to just silently fail like this. While it might be possible to enable WordPress debug logging and ultimately figure out what’s going on, in my experience first impressions are indicative when it comes to WordPress plug-ins, so I’m not going to spend time trying to get a plug-in to work at all when it’s probable it’ll have numerous other problems anyway.

Syntax-highlighting Code Block (with Server-side Rendering)

Nominally a fork of Code Syntax Block that renders server-side instead of client-side, although it uses a different engine – Highlight.php instead of Prism.js.

highlight.php is a PHP port of Highlight.js. It’s unclear to me how closely or promptly that tracks changes to the original JavaScript library.

It’s open source and free (as is the highlight.php engine underneath it).

Performance

The default theme is particularly bland. It’s actually hard to judge its understanding of Swift purely from its appearance since so much of it looks the same.

It’s noteworthy as a particularly hostile plug-in (with its default theme) for colourblind viewers, due to its use of very similar shades for almost everything, and in particular its use of red vs grey in a way which makes them virtually indistinguishable to a significant portion of the population. It’s not the only plug-in to be thoughtless in this way, but it is the worst.

It does come with a lot of other themes – nearly ninety at time of writing – but you’d be forgiven for thinking it does not, as it puts the theme selection setting in a surprising location – the ‘Customize’ section of WordPress’s Appearance settings. While this actually makes tremendous sense, no other syntax-highlighting plug-ins put their settings there. It’s hard to hold that against this plug-in, for being the one plug-in which (arguably) does the right thing, but I almost overlooked this critical functionality – I only discovered it by chance because I happened upon its Advanced Usage documentation.

That all said, one thing the bland default does have going for it is that the visual sameness helps to slightly obscure how poorly the plug-in understands Swift.

For example, it:

• Doesn’t understand @-attributes, such as macro and property wrapper invocations.
• Has no idea about the difference between function parameter labels and parameter arguments.
• Doesn’t consistently recognise references to properties, such as when they’re part of KeyPaths.
• Doesn’t understand some important keywords, like async & await.
• Doesn’t recognise method calls consistently (e.g. pack vs reduce & map in the example shown).
• Doesn’t understand raw strings (though it does handle multi-line strings correctly).
• Is fooled by the use of keyword-looking names in places where they aren’t keywords, e.g. the default static property of HomeItem.

It’s pretty apparent, especially once you look at the HTML itself, that it’s doing only a rudimentary analysis mainly based on a hard-coded list of keywords and heuristics like whether words start with capital letters. That’s why it confuses literals (strings & numbers) with type names, function names with property names, and so forth. It’s not the only plug-in to try to fake it with such a simplistic algorithm, but it does the worst job of pulling it off.

It renders keywords in bold (like Xcode), which greatly aids readability.

Since it uses the built-in WordPress Code block as its basis, and doesn’t muck with the fonts, it defaults to whatever the active WordPress theme uses. As shown in this example, with GeneratePress, that’s not even necessarily a monospaced font! Worst, the plug-in has no built-in configuration option for font (although you can use custom CSS to override it).

Pros

• Extends the built-in, standard Code block. This makes it comparatively trivial to adopt if you’ve already got Code blocks on your website (although you may still need to go through and customise some things, such as the language in case auto-detection doesn’t work correctly).
  
  This also makes it easier to switch syntax-highlighting plug-ins, provided that the one you switch from or to also supports the standard Code block, which is sadly a minority of them.

Cons

• No official theming support.
  
  You can use custom CSS to re-theme it, thanks to its use of sensible class names for its spans, but other than fixing its bland default colours you can’t really improve it much, since a lot of the code is emitted as runs of plain text because of the plug-in’s very poor understanding of Swift.
• No global settings – if you decide to change any settings, at any point, you have to manually find and adjust every existing code snippet manually.
  
  This might be considered a positive by some users, where they want existing content to remain as-is. However, some plug-ins offer both a global setting and the ability to override that on a per-case basis, providing more flexibility.
• Very limited settings – just the language (if you don’t want to rely on auto-detection), which line(s) to highlight, whether to soft wrap, and whether to show line numbers.

SyntaxHighlighter Evolved

This is what I was using for years. It’s completely free and open source. It uses a proprietary syntax parsing system based on regular expressions.

Performance

It’s an interesting one, because it actually understands so little Swift syntax that most of it is bucketed together as ‘plain’ text. However, because it renders ‘plain’ text in a colour other than black, it gives the surprisingly convincing (at a glance) illusion that it understands much more than it really does.

Overall its rendering is close to Xcode’s, which is very surprising given its highly rudimentary grammar parser.

It is actually pretty good about identifying keywords – it actually gets async which many do not – but it doesn’t understand them with context, e.g. it mistakes the default static property of HomeItem with the default keyword.

It renders keywords in bold (like Xcode) which greatly aids readability, although note how (unlike Xcode) it messes up the letter spacing as a result (this is a result of the font used – Monaco – and thus can be fixed by overriding that with a better font, e.g. SF Mono).

While it covers up a lot of its ignorance with its clever colour choices, there’s still a few important things that it gets visibly wrong. For example, it:

• Doesn’t understand @-attributes, such as macro and property wrapper invocations.
• Has no idea about the difference between function parameter labels and parameter arguments.
• Doesn’t understand raw strings.

Its choice of Monaco as its font is… interesting, although modern versions of Monaco are thankfully a little smoother than their 1980s ancestor. That’s easy to override, however, via custom CSS in a suitable WordPress-generic stylesheet (the plug-in doesn’t provide any direct way to manipulate styling, beyond choosing from a short list of built-in themes).

Pros

• Most of its settings are global. So changing themes for a whole site is trivial.
• Uses sensible HTML structure and class names, so it’s easy to unofficially re-theme (although it has a very limited vocabulary of grammar, so you can’t greatly improve what you see here).
• Supports end-user editing of the code (with the syntax highlighting updating appropriately). This is purely superficial text editing – there’s no support for interpreting, compiling, or executing the code. So I’m not really sure what the point of this feature is, but I list it here since it is unique to this plug-in (amongst all those I tested).

Cons

• Doesn’t formally support light/dark mode (as do none of the plug-ins tested). Colours are fixed (to whatever theme you choose) irrespective of the end-user’s light/dark setting (again, same as all the other plug-ins). However, one difference versus all the other plug-ins is that this one doesn’t work properly with WP Dark Mode – it remains in light mode even while the rest of the page renders correctly in dark mode.
  
  I strongly suspect the fault lies in WP Dark Mode, not SyntaxHighlighter Evolved, but irrespective it is there and might be a deal-breaker if you’re particularly attached to WP Dark Mode.
• Doesn’t render the syntax highlighting in the Gutenberg editor, so you’re stuck with the generic pre appearance there.
• Uses a custom Gutenberg block type, rather than just extending the standard Code block. So you can’t just upgrade your whole existing site – you have to manually go through and find every existing Code block, and manually migrate each one.
• Doesn’t get updated super often, although it has been around for years and has generally kept up with new WordPress versions, eventually.

Urvanov Syntax Highlighter

A fork of the abandoned Crayon Syntax Highlighter that uses its own syntax-highlighting engine.

It’s open source and free.

I almost didn’t include this because (a) it’s really very broken and (b) it doesn’t really support Swift at all. I strongly recommend against using it, for numerous reasons.

Performance

Pretty terrible, in a nutshell. I’m not going to go into full detail here because the plug-in is largely broken anyway (details shortly, in the Cons section).

Ironically it works better out of the box than if you actually configure it “correctly”; it doesn’t recognise this example as any specific language and falls back to some generic “Default” grammar parser. If you explicitly set it to Swift, the syntax highlighting actually gets markedly worse, and it’s no surprise why – its Swift grammar definition is nearly a decade old, dating back to Swift 1.0 in 2014!

One of its most egregious rendering problems is that it translates various special characters – [, <, >, etc – to their escaped HTML entities. This can be ‘corrected’ in its settings – it has a “Decode HTML entities in code” option – but that’s a hacky bandaid over the bug, that precludes you from actually using HTML entities in your code example (so you can’t use this plug-in for the HTML language itself).

Another rendering annoyance is that it makes the code block’s width 100%, irrespective of the actual width of the code. Most of the plug-ins do that, actually, but it’s much more apparent with this one because of its use of a visual border and alternating line background colours. You can configure a maximum width in its global settings, but (as with most of these plug-ins) there’s no (built-in) way to make it size to fit.

On syntax understanding itself, it basically has none. It simply recognises some fairly general syntax patterns, such as strings, literals, and parenthesis-indicated function calls. It doesn’t recognise most keywords, even.

Pros

• Very configurable – perhaps the most configurable plug-in tested. Beyond just theming options – including the ability to easily change the font from its default of Monaco – it includes options rarely covered by other plug-ins such as margin customisations.

Cons

• Nominally offers a Gutenberg block, but it doesn’t work – you cannot actually edit the textual contents, in the Gutenberg editor, and it doesn’t render at all on the actual published page. Thus you can only use the plug-in by having it take over existing <code> and/or <pre> blocks…
• Takes over all existing <code> and <pre> blocks by default, even those by other plug-ins, and those that don’t contain code at all (e.g. where you were simply presenting monospaced text such as Terminal output). You can configure this in the settings, including turning it off, but given the Gutenberg block doesn’t work, this is the only way to actually use the plug-in.
  
  
  
  I spent some time playing with different combinations of these settings, but many combinations are inexplicably unusable – they just result in broken rendering – and I couldn’t find anything that improved on the default behaviour.
  
  As such, this is an especially all-or-nothing syntax highlighter. It really doesn’t play well with others.
• Since it just takes over existing <code> and/or <pre> blocks, there’s no per-use customisation possible – everything is exclusively controlled through global settings, including the code language.
• By default adds its CSS & JavaScript files to every page load, plus some inline CSS & JavaScript, irrespective of whether the page actually needs it or not. This can nominally be corrected in the settings, via the “Attempt to load Crayon’s CSS and JavaScript only when needed” option, but I didn’t test it (and it’s not encouraging that it’s both disabled by default and uses the word attempt, both suggesting this feature doesn’t work reliably).
  
  And they’re not entirely trivial files, either, even though rendering is done server-side – its JavaScript is 65 KB alone! Its CSS is another 28 KB. With Brotli compression they’re ~18 KB. They compress well in part for the same reason they’re so egregiously large – the use of “urvanov-syntax-highlighter” / “urvanov_syntax_highlighter” prefixes on so many of the names. This bloats up the page source as well, with oversized HTML class names for every snippet of styled code.
• Doesn’t render the syntax highlighting in the Gutenberg editor, so you’re stuck with the generic pre appearance there.

The winner

…is hard to pick unilaterally. Each plug-in has significant limitations or trade-offs. Which is best may depend on your personal preferences and specific needs.

Most of the plug-ins do a pretty atrocious job at actually understanding Swift, and at best for them it’s a question of how well they can fake it through clever heuristics and styling choices. SyntaxHighlighter Evolved warrants an honourable mention in this regard for doing a particularly impressive job despite its very limited brains. There’s a reason I used it for years with relatively few complaints, and if it hadn’t had issues with WP Dark Mode – before I realised WP Dark Mode was buggy anyway and had to be replaced – I probably wouldn’t have bothered doing all this competitive research, and wouldn’t be switching away from it.

The most common engines used by syntax-highlighting plug-ins are Prism.js and Highlight.js / Highlight.php, but frankly they’re bad at Swift – a situation that’s unlikely to change given Swift is such a niche language for them; they’re clearly focused on browser languages like JavaScript, HTML, and CSS. Even that aside, they tend to use client-side rendering which is slower and buggier.

It currently does a somewhat average job in understanding Swift and rendering it pleasingly – just like all the plug-ins tested – but it seems to have the most promising foundation, being based on the same grammar & theme files as are used by Visual Studio Code (and GitHub). So it has the possibility of significant improvements in future; at the very least it would make sense for the Swift community to focus on it since the benefits will be applicable not just to WordPress websites but also Visual Studio Code and GitHub.

Refinements to Code Block Pro

Every light-style theme available with Code Block Pro – including the paid expansion pack – has significant rendering errors for Swift, but after spending an egregious amount of time exploring the themes and experimenting with fixes for them, I’ve concluded that Light Plus is the least bad option. With some crude but simple CSS I’m able to adjust its appearance as shown here, which is loosely styled after Xcode’s default (light mode) theme.

I didn’t do much to accomodate Dark mode, limiting my modifications there to merely using SF Pro (“system-ui”) for comments. I don’t use Dark mode myself, so I might not have a good eye for what looks good there, but the default colours (from the simple inversion by the Dracula Dark Mode plug-in) seem alright to me. And pragmatically, I’d have to overwrite every colour used in the theme in order to ensure no rendering issues, and that’s a whole lot of CSS I don’t want to write nor bloat my page loads with.

I also turn on “Disable padding” in its “Extra Settings”, as by default it uses (a) hard-coded padding dimensions, in pixels and (b) padding, not margins. A strange choice, but at least it has the option to disable it.

div.wp-block-kevinbatdorf-code-block-pro {
	font-family: "SF Mono", SFMono-Regular, ui-monospace, monospace;
	width: fit-content;
	margin: 1em;
	
	& span[style*=\#0000FF], span[style*=\#AF00DB] { /* Keywords */
		font-weight: 675;
		color: #9B2393 !important;
	}
	
	& span[style*=\#008000], span[style*=\#81f179] { /* Comments */
		font-family: system-ui !important;
		font-style: italic;
	}
	
	& span[style*=\#008000] { /* Comments */
		color: #5D6C79 !important;
	}
	
	& span[style*=\#001080] { /* Properties */
		color: #3E8087 !important;
	}
	
	& span[style*=\#795E26] { /* Function names and argument labels */
		color: #804FB8 !important;
	}
	
	& span[style*=\#267F99] { /* Type names */
		color: #4B22B0 !important;
	}
	
	& span[style*=\#A31515] { /* String literals */
		font-weight: 500;
		color: #D12F1B !important;
	}
	
	& span[style*=\#098658] { /* Numeric literals */
		font-weight: 500;
		color: #272AD8 !important;
	}
}

What are other websites using?

I figured it might be helpful to look at what other Swift-code-rendering websites use, to see if there’s any I missed (there wasn’t) and which the community seems to believe is best.

• Swift by Sundell is using Publish and the Splash plug-in. Splash seems to do a pretty good job – clearly better than any JavaScript or PHP syntax highlighters.
• Hacking with Swift is using WordPress and ultimately Prism.js, although I’m not sure through which plug-in (possibly Code Syntax Block).
• Cocoa with Love might be using some Ruby-based platform or static generator, but it’s clear it’s using Rouge for syntax highlighting.
  
  Sidenote: Rouge seems to do a decent job of correctly identifying tokens and their types, although its underlying model looks pretty simplistic (it tends to default to the “n” class by default, meaning “name”, meaning it doesn’t really know if it’s a parameter label, parameter name, type name, etc).
• Donny Wals is using WordPress with the Syntax-highlighting Code Block plug-in, which uses Highlight.php (based on Highlight.js).
• Matteo Manferdini is using WordPress with the GeneratePress theme (same as this site, at time of writing) and ultimately Prism.js, likely through Code Syntax Block.
• NSHipster appears to be statically generated with a bespoke tool written in Ruby using a custom fork of Rouge.
• The old Swift Blog uses… I don’t know. Possibly a proprietary system, for both the platform and the syntax highlighting. I didn’t find any identification or indicators otherwise of any particular library.
• The newer Swift Blog uses… possibly the same mystery platform as the old one. But it does clearly use Rouge for syntax highlighting.
• Swift Evolution Monthly is hosted on Substack and doesn’t do any syntax highlighting at all!
• Swift with Vincent is hosted on Squarespace, which ultimately uses Prism.js.
• Swift with Majid is statically generated using Jekyll and uses Rouge.
• Swiftinit (by Dianna a.k.a. “taylorswift” / “tayloraswift“) uses a proprietary platform (written in Swift). The syntax highlighting is presumably also proprietary.
  
  Sidenote: there’s not a lot of syntax-highlighted code on Swiftinit (mostly it’s in some hidden blog posts from 2022), but what’s there looks pretty similar to what Rouge generates. It does a pretty good job of correctly interpreting the syntax, although there’s not a great deal of apparent fidelity – mostly it’s just dividing things into formal names (types, functions, etc), variables, keywords, and everything else.
• SwiftLee is using WordPress and the Code Syntax Block plug-in, which is Prism.js underneath.
• SwiftRocks is using Bootstrap and Prism.js.
• SwiftUI Lab is using WordPress and the Prismatic plug-in, which is configurable to either Prism.js or Highlight.js underneath; the site has elected to use Prism.js.
• TrozWare is using Hugo and Prism.js.
• Yet Another Swift Blog is statically generated using Jekyll and uses Rouge (though oddly I also see fragments of Prism.js and Highlight.js on the site, although I didn’t see any actual use of them to render code).

If you’re keeping score, that’s (syntax-highlighter-wise):

• Prism.js: 7
• Rouge: 5
• Unknown: 2
• Highlight.js: 1
• Splash: 1

And platform-wise:

• WordPress: 5
• Unknown: 3
• Jekyll: 2
• Proprietary: 2
• Bootstrap: 1
• Hugo: 1
• Substack: 1
• Squarespace: 1
• Publish: 1

It’s notable that not one is using Code Block Pro nor the underlying Shiki engine, even though (with the serious caveats mentioned earlier) they do the best job of actually understanding Swift.

1. Strictly-speaking not for any technical reason, as the plug-ins could run more advanced tooling on the server (as some bespoke CMS’s do), but I have not encountered any WordPress plug-in which does so. ↩︎
2. Technically you can do it with just custom CSS, by overriding your theme’s defaults inside a @media (prefers-color-scheme: dark) block, but this is likely impractical for all but the most simplistic and static WordPress installations – you have to be sure you catch every GUI element and colour. A good plug-in will dynamically rewrite the CSS client-side, ensuring everything is covered. ↩︎

iTools

Long before iCloud, iTools was was of Apple’s first forays into web services as we recognise them today. The headlining features were the ability to create an email address (free!) under the @mac.com domain (which I still use to this day!) and an online file storage and sharing system called iDisk, which was the foundation for several other services & tools within the bundle including HomePage and Backup.

Backup wasn’t exclusively tied to iDisk, and I used it (in the later .Mac era) for a couple of years to backup my essential documents to iDisk and my entire computer to a external hard drives and CDs. I think it was my first real backup system…? And I still have all those backups!

I don’t recall that I used iTools, or at least not in any serious way. I was still in high school when it came out (just), going into university, and I recall using my university email address during that time.

If I remember correctly, iTools was pretty well received by actual users but panned critically, with the press and technorati unimpressed by it in light of antecedents like Hotmail (launched three years earlier in 1997) and numerous existing “DIY” website builders and free webhosts (GeoCities!).

There was also some resentment due to its Mac-only nature, although technically most of the services worked through a web browser on any platform, you just couldn’t create an account except on a Mac.

Remember, too, that Mac OS X didn’t exist when iTools launched. It was Mac OS 9 – retroactively named “Classic Mac OS” re. Rosetta etc – and for Mac users the world was a very different place. Once Mac OS X did launch, iTools became even better with integration into the Finder (for iDisk). This was over six years before Dropbox even existed.

Hotmail and lesser known contemporaries pioneered free email, but with tight limits on usage (e.g. only 2 MB of email storage, enough for about two modern spam emails!). .Mac offered 50 MB (upgradable to 2 GB for a fee). This was three years before Gmail was launched, too (at which time the word “unlimited” started to get thrown around, although technically Gmail only offered 1 GB initially).

My old website dates back to at the latest September 2005 when I launched my blog, although I’m pretty sure I’d been using it for quite some time before that (though the Wayback Machine didn’t notice it for three more years, until September 2008 😂).

It took a little bit of effort to get it functioning again – it contained a lot of references to 3rd party resources (Google Adsense & Analytics, Haloscan, etc) that are no longer valid / necessary, as well as to some more intrinsic .Mac HomePage functionality that’s long gone, like iDisk (the early file-sharing functionality a la Dropbox / iCloud Drive). I pruned out most of that for the sake of removing long-dead, broken links & images.

.Mac

.Mac was a relaunch of iTools – a major version update in technical terms, but also a major departure in that it was no longer free for all Mac users. You now had to buy it! For actual money! And keep paying for it, every year, like a caveman! $100!

I still remember receiving an actual box for .Mac, and I suspect that was when I first really used the service. I think I might have received it through the AUC as part of their scholarship program which effectively launched my career, lining me up to work at Apple, move to California, and all the rest.

As for .Mac, it was somewhat ill-received, and despite Apple bragging about receiving 100,000 sign-ups, the general attitude was that it was too little for too much. It didn’t help that it then went years without much improvement or attention from Apple.

The name was a bit weird, too – clearly playing on the .com TLD, but in an era long before the expansion of TLDs, back when there was basically just .com, .net, .org, and .edu¹. It’s interesting that to this day there’s still no .mac TLD (although there is .apple, albeit for no apparent reason since it’s retained by Apple for their exclusive use, and they don’t use it).

Years later, in 2008, it was rebranded and “relaunched” yet again as MobileMe. I for one don’t recall ever having significant issues with MobileMe, but it was widely lambasted for being unreliable. I certainly don’t think it was any worse than iCloud (especially in light of macOS Sonoma’s catastrophic embuggering of iCloud Drive).

Incidentally, as part of this trip down memory lane, I also went through and fixed the broken images on my very earliest blog posts, that didn’t originally import into WordPress when I migrated off of MobileMe HomePage in 2012, when the product was shut down by Apple (in favour of iCloud, which was mostly a PR move to distance themselves from perceived reliability problems with MobileMe – notably not an actual improvement in reliability, which to this day remains sorely needed).

1. Well, plus .gov and .mil, but regular people never encountered those in everyday life. ↩︎

While I was doing that, I figured it was high time to drop the subdomain, so now it’s just https://wadetregaskis.com, instead of https://blog.wadetregaskis.com. Blogs are so last year.

Previously I was using Gandi.net (I recall choosing them because they were touted as a particularly privacy-centric host) shared webhosting. I’m now using an unmanaged VPS from IONOS. This is far superior – site performance is much higher, I can finally use modern web technologies like TLS 1.3 and AVIF¹, and frankly it’s just deeply satisfying to have a whole [virtual] machine at my disposal. It might be a gateway to bigger things.

I chose IONOS because they offered the best apparent value amongst hosts that seemed well-reviewed. I’m now paying just a third of what I was at Gandi.net (for what amounts to at least 2x the CPU performance and 4x the RAM!). They also include a full copy of Plesk, which has proven a net win in getting everything set up and configured – notwithstanding some serious initial issues with it, that ended up requiring me to reimage the whole VM and restart from scratch. 😒

The process took over two full days, partly because of the aforementioned Plesk issue which cost me nearly a full day by itself, and otherwise because of just a whole bunch of issues along the way. e.g.:

• File transfers (via HTTPS or SFTP) to & from Gandi are slow. They always have been – it’s one of several things that always bothered me about Gandi.
• TCP connections to Gandi tend to get killed if they hang around for any significant amount of time (such as for large file transfers over HTTPS or SFTP²).
  • This in turn exacerbated a few bugs in Cyberduck whereby automatic retries don’t work and I had to manually relaunch Cyberduck completely between retries (otherwise it locked up).
    
    I partly addressed this by using Transmit instead, which isn’t entirely immune to Gandi’s bugginess but seemed to hit it much less often. And is also a much more elegant application, in any case.
  • Combined with the general slowness, this meant it took most of an entire day to copy out the compressed copy of the old site – which was just a few gigabytes.
• I struggled to find a good way to migrate the site before committing to the actual domain name migration. I had never migrated a WordPress site between hosts – never even restored in-place from an existing backup – so I had no real idea to what degree it would work.
  
  This would have been easier without TLS. I long-ago enabled HSTS for my site, and I technically could have worked around that in various ways, but no matter which approach I took I think it would have been challenging.
  
  Ultimately I just got too frustrated and said “screw it, I’ll switch the domain name and then figure out how to move WordPress”. Thankfully almost nobody visits this site, so breaking it for a day or so was inconsequential.
  • I made this slightly harder on myself by insisting on a “proper” TLS certificate for the new host – and therefore from IONOS since they include one free with each VPS – rather than using Let’s Encrypt (support for which is provided by a pre-installed extension to Plesk). IONOS’s control dashboard didn’t particularly want to issue the certificate while non-IONOS nameservers were used for the domain, although eventually I coaxed it into doing so.
• It took a while to figure out how DNS needed to be configured, between the old host (and registrar), the new host, and Cloudflare. DNS isn’t that complicated in principle, I just wasn’t all that familiar with it. I’ve added TXT records before and done a few other tweaks, but nothing of the complexity of multiple intertwined nameservers and non-trivial subdomain routing.
  
  Although in retrospect having Cloudflare in front of everything perhaps made it easier since ultimately I just had to change settings there, as opposed to having to move nameservers.
  • DNS propagation delays were a significant irritation and cause of substantial delays. After several key changes, I had no choice but to wait an indeterminate number of hours before I could see their effects and move on to subsequent steps.
    • macOS bugs whereby it ignores the last entry in /etc/hosts³ also didn’t help.
• UpdraftPlus kept failing to restore the new site from a backup of the old (ultimately it turned out to be an OOM-killing problem, easily fixed by enabling some swap space).
• Many miscellaneous bugs in Plesk, half of which I’ve already successfully repressed, but as merely a few examples:
  • Plesk’s WP Toolkit extension believes it can set up a crontab entry to poke wp-cron.php periodically, but it can’t (because apparently you can’t invoke that directly via php, you have to actually go through Apache with a real HTTPS request – I never got to the bottom of why).
  • Sendmail / postfix don’t work out of the box with Plesk; WordPress & Plesk just silently fail to send emails. I never found any way to get them to log their failures, but I did ultimately get it working through trial-and-error (and I can’t even say what specific configuration change(s) actually fixed it).
    • It also took a while to figure out how to properly set up DKIM, SPF, and DMARC, although that was relatively straightforward once I found this documentation.
  • After using Plesk and staying logging in just fine for over a day, on multiple computers, it suddenly decided it would log me out instantly almost every time. This is apparently a common issue, and through sheer stubbornness of countless login cycles I was able to get to the “Allow IP address changes during a single session” checkbox, which fixed it for me.

I’m glad it’s done, and there is a solid sense of satisfaction with having conquered the litany of bugs, design flaws, and limitations throughout the whole process.

But I really hope I don’t have to move hosts again anytime soon.

1. …because I can install modern versions of basic tools & libraries, like curl and ImageMagick, that support things like TLS 1.3 and AVIF. ↩︎
2. Made worse by Gandi’s weird SSH server being incompatible with rsync, thus forcing the use of all-or-nothing transfers over SFTP. ↩︎
3. It always ignores the last line of the file, so you have to explicitly add a trailing line return. This is actually not uncommon with Unix tools of a certain pedigree, from before good design, robustness, and user-friendliness were values. ↩︎

Bafflingly there’s apparently no way to deep-link into Mona (or ‘Mastodon’ generally), so apparently you’ll have to copy-paste that user ID into your client of choice’s user search.

I was surprised how much traffic it brought to my site – my vague intuition was that with the content repeated wholesale there’d be no motivation for folks to visit the original.

I was also slightly surprised by the comments section (on Nikon Rumors), though upon reflection I probably shouldn’t have been. As Peter (Nikon Rumors admin) quipped to me, “Welcome to the Internet :)”.

Roughly-speaking, it seems to break down into:

Constructive

A very small portion of the feedback was constructive (and sometimes intentionally so, even), e.g. typos, my embarrassing mislabelling of a jaguar as a leopard, etc. Some was interesting in revealing unintended ambiguity in my phrasing – I always find it intriguing to find valid, different interpretations of things I wrote. It’s a worthy challenge to try to write without ambiguity.

I really appreciate when people provide useful feedback – even if it’s not well-motivated. It’s so rare in life to receive useful feedback.

Missing context

A lot of the feedback was because of missing context – many folks assumed it was a review, not merely a random collection of observations, and therefore meant to be balanced & comprehensive. Or that I’d only use the Sigma 150-600 C with the Z9 (I did mention use of other lenses, but apparently too briefly or obliquely for many to register).

That’s useful to know because it revealed I was unwittingly assuming folks would read the first impressions first, which provided a bit more context, and also assuming a lot about the reader’s mindset coming in – i.e. that they’d implicitly understand that a lot was tongue-in-cheek.

Missed sarcasm / irony / frivolity

It seems apparent from some comments that my sense of humour / writing style just didn’t sit well with many folks. I’m used to that – I hate irony and never use it all the time.

The Nikon Z9’s acrobatic abilities seemed to particularly rub many folks the wrong way, which even in retrospect I still find odd because it seems so obviously (a) a very minor concern in any case and (b) just funny, really. Many folks did wonder aloud why I had my camera loose in a car anyway, which is a totally valid question and one I didn’t think for a minute to address when I wrote the article.

(for the record, it’s mainly because I’d never really needed to before, and I like having the camera readily available – plus I’ve since figured out that I can kind of wedge the Z9 under the seats, in the rear footwells, so problem solved!)

Mean

Sadly, most feedback was acerbic and ill-intentioned. Thankfully the novelty of the occasion neutered the mean-spirited comments, and they’re easy to skim over because they tend to be repetitive, pithy, and thus easy to identify. I’m a bit mystified as to why those folks spend their time that way, though. Some kind of game? Catharsis?

A few hours later, Gandi.net was working again, but my site wasn’t.  Sad panda.

Long story short, I used up all the disk space – and by “I”, I mean something – still haven’t figured out what, yet.  Apparently when you use up all the space, that simply kills the VM without any notification (their dashboard for my VM still claimed it was running just fine, no problems detected, which was obvious crap).

That said, their tech support identified the problem quickly and were ultimately able to rectify things for me (after first suggesting I delete some stuff myself, which I tried only to find that when your Gandi VM is wedged in this state, you can’t log in via SSH nor delete anything via SFTP, and those are your only two means for deleting any files…).

As far as I can recall, this is the first time my site’s actually been down in the ~four years I’ve hosted with them (other than a few errors on my part when messing with WordPress etc).

Actually, Suffusion was pissing me off as per usual, and I accidentally applied a new theme when intending only to install it (apparently ‘Activating’ a theme applies it, which is sensible in hindsight but not as clear as it should be given how plug-ins work).  Turns out, you can’t easily go back – changing themes permanently wipes out a bunch of settings.  #%@!

And as per usual the backups plug-in I have installed had silently wedged itself and failed to back anything up for a couple of months.  Sigh.

WordPress is kinda shit.  It’s a mess.  A complicated, slow, buggy mess.  If I actually cared to spend any more time on this site, I’d start by looking for another platform.

So I’ve changed the font of this ‘ere website to something that looks nicer on the iPad 3.  It looks less impressive on pretty much any other device.  So get an iPad 3.

#!/usr/bin/python

import errno
import os
import sys
import urllib


if 3 != len(sys.argv) or '-h' in sys.argv or '--help' in sys.argv or 'help' in sys.argv:
    print >> sys.stderr, '''Usage: {0} SITE_FOLDER NEW_BASE_URL

SITE_FOLDER is the path to the local folder containing the site to be redirected.
NEW_BASE_URL is the base URL of the new site, to which the redirects will point.  It is up to you to ensure proper URL escaping is performed; it will not be done by this script (except for the paths this script generates, to then append to this base URL).

For example, if the local path /www/mysite/ is used for SITE_FOLDER, and NEW_BASE_URL is given as "http://foo.com/", then for a file /www/mysite/index.html a redirect will be created to "http://foo.com/index.html".'''.format(sys.argv[0])
    exit(errno.EINVAL)

(_, siteFolder, newBaseURL) = sys.argv

if not newBaseURL.endswith('/'):
    newBaseURL = newBaseURL + '/'

siteFolderPathLength = len(siteFolder)

if not siteFolder.endswith('/'):
    siteFolderPathLength += 1

for (folder, subFolders, files) in os.walk(siteFolder):
    relativePath = folder[siteFolderPathLength:]
    
    if relativePath:
        relativePath = relativePath + '/'
    
    relativePath = urllib.quote(relativePath)
    
    for file in files:
        (_, fileExtension) = os.path.splitext(file)
        
        if fileExtension in (".htm", ".html", ".xhtml"):
            replacementContents = '''<html>
    <head>
        <meta http-equiv="refresh" content="0;url={0}{1}{2}">
        <script src="http://www.google-analytics.com/urchin.js" type="text/javascript" />
        <script type="text/javascript">
            _uacct = "UA-103051-1";
            urchinTracker();
        </script>
    </head>
    <body></body>
</html>'''.format(newBaseURL, relativePath, urllib.quote(file))

            #print "Would replace {0}/{1} with:\n\n{2}\n\n".format(folder, file, replacementContents)

            with open(os.path.join(folder, file), "w") as f:
                f.write(replacementContents)

What’s more difficult, however, is updating all the absolute paths and other references to homepage.mac.com within the HTML files, now that they’re hosted on wadetregaskis.com. I did a bunch by hand, then realised there’s over a thousand HTML files in the Photos subfolder that each contain many homepage.mac.com links. Sod.

I had a quick look for a utility to perform this, but found only a handful, and none that support Macs. I’m sure there’s tools out there, probably Perl or Python or Ruby scripts, that would ultimately work, but finding them is probably more trouble than just reproducing them myself.

I also tried BBEdit, knowing it had FTP support (but no FTPS, dangerously), but it doesn’t appear willing to perform a search & replace via it. Bollocks.

Maybe I can write another script, but I’ve never done FTPS in Python before. Hmm…

So no, I didn’t write all my journal entries between midnight and eight in the morning. Just ignore WordPress – try not to make eye contact as you back away, slowly…

So I had no choice – I had to write my own converter.  A quick and very nasty hack in Python; 175 lines and a few hours later, with one false start (WordPress interprets line returns in its XML as essentially <br>s, which is awkward since iBlog hard wraps everything at ~80 columns).  But it’s done.  Well, mostly… I only pulled in the text, not the multimedia – pictures, mainly.  I guess I’ll have to think about how I can fix all those up… thankfully most of my old posts didn’t make use of any additional “attachments”, so it might even be feasible to fix things manually.

I contemplated generating replacement HTML files for all the existing content on MobileMe, with redirects to the new equivalents here… but then I thought, holy crap, that’d be a lot of work.  And for something which is going irreversibly dark in four or five months anyway. So to those who have bookmarks, we salute you..

For example, I want icons for each category.  It’s not an original idea – I did as much with my original journal years ago – and you’d think it would be brain-dead simple.  Indeed, this “Suffusion” theme even shows what you’d think are generic, placeholder icons for categories.  All ready to be replaced with the real ones.

Only, not really.  Apparently it just really likes showing these bland default icons repeatedly, redundantly, and in fact without any way to even turn them off (in the sidebar).  WTF.

I’m very quickly getting the feeling that when it comes to WordPress, you either find a theme that is exactly right to begin with, or you just concede defeat.

I’ll be moving the old site and most of its content over here – I may even go to the effort of importing my old journal into this new, shiny, WordPress-powered version.  Or not.  We’ll see how easy that is.