Category Archives: WordPress

WP-GeSHi-Highlight 1.3.0 released

I have released version 1.3.0 of WP-GeSHi-Highlight. WP-GeSHi-Highlight is a popular code syntax highlighting plugin for WordPress, based on the established PHP highlighting library GeSHi.

These are the changes compared to version 1.2.3:

  • Enhance compatibility of the default stylesheet with a large range of themes by increasing the specificity of certain CSS selectors and by adding more style directives. This ensures a better out-of-the-box experience. Thanks to Pascal Krause for reporting an incompatilibity with Twenty Ten.
  • Increase compatibility with CDNs: fix double slash appearing in CSS file URL.
  • Remove redundant call to wp_register_style().
  • Change style sheet ID prefix, add newline characters to GeSHi CSS code output.
  • Improve code documentation and readability.

In fact, this update contains a considerably consolidated default stylesheet (with just a minimal set of changes). I have verified that it works well with all recent versions of the important official themes:

  • Twenty Ten (version 1.9)
  • Twenty Eleven (version 2.1)
  • Twenty Twelve (version 1.7)
  • Twenty Thirteen (version 1.5)
  • Twenty Fourteen (version 1.4)
  • Twenty Fifteen (version 1.2)

I have also tested the new default style sheet with the following popular themes: Vantage, Customizr, ColorWay, Zerif Lite, Responsive, Storefront, Virtue, evolve, Make, Sparkling, Spacious, Enigma, Sydney, Point, Interface, SinglePage.

I want to use this opportunity to stress how much I like the recent community developments around WP-GeSHi-Highlight. Almost five years have passed since I first released this plugin to the WP repository, and I never really put effort into spreading it. Nevertheless, according to the WordPress statistics, it is used on more than one thousand websites. I have searched the web to find a few examples about who uses this plugin for which purpose, and want to share two of my findings:

  • In this StackOverflow thread, Aaron Bertrand, a ninja database expert, revealed that he likes the GeSHi-based approach so much (and he uses WP-GeSHi-Highlight in his blogs), that he was willing to provide a huge bounty to someone helping him out to improve the syntax highlighting for the T-SQL language in subtle ways. Another ninja joined the discussion for helping Aaron, and Aaron had more wishes like “There’s always one little extra thing, right? I promise this is it. I want to color the N prefix on Unicode strings in red.”. They found their solution, great. I proposed to them to contribute their findings upstream, straight to GeSHi, so that I, further downstream, can incorporate them in WP-GeSHi-Highlight at some point. I love this.

  • On Make Create Reiterate, Tina Dvyver uses WP-GeSHi-Highlight (and writes about it) as of its support for an exotic language in the world of highlighters, X++. What I like about her blog is that she actually took her time to adjust the default stylesheet to her needs, and that she came up with a neat way to hide the dots in the numbered list, when using line numbering. She writes about it here.

One more thing I want to mention: in the past days I had a productive discussion with two users of this plugin, in this support thread. Turns out that WP-GeSHi-Highlight was not responsible for the issue reported there, but this discussion still lead to fixing the double-slash issue mentioned above in the change log. It also lead to me knowing of one more person who actively transitioned from WP-Syntax to WP-GeSHi-Highlight, and to one more review on the wordpress.org plugin page.

I realize that I should put more effort into spreading this plugin, as it has obvious architectural advantages over heavy client-side highlighters. Unfortunately, most of the “Top X syntax highlighting plugins for WordPress” blog posts around the web do not really clarify the significant difference between back-end highlighters and client-side ones. I’ll possibly cover that in a future blog post.

Structured data for Google: how to add the ‘updated’ hentry field

This is a WordPress-specific post. I am using a modified TwentyTwelve theme and Google Webmaster Tools report missing structured data for all of my posts:

Missing "updated" field in the microformats hatom markup

Missing “updated” field in the microformats hatom markup.

In particular, it is the updated hentry field that seems to be missing. TwentyTwelve, like many themes, uses the microformats approach to communicate structured data to Google (also to others, it’s just that Google is a popular and important consumer of this data). How to correctly present date/time information to Google? A quote from their microdata docs:

To specify dates and times unambiguously, use the time element with the datetime attribute. […] The value in the datetime attribute is specified using the ISO date format.

And a quote from their microformats docs:

In general, microformats use the class attribute in HTML tags

It appears that we can combine the approaches. Might be dirty, but it works. So, what you might want to have in the HTML source of your blog post looks like this:

<time class="updated" datetime="2015-02-28T18:09:49+00:00" pubdate>
February 28, 2015
</time>

The value of the datetime attribute is in ISO 8601 format and not shown to the user. It should contain the point in time the article/blog post was last modified (updated). It is parsed by Google as the updated property, because of the class="updated" attribute. The string content of the time tag is what is displayed to your users (February 28, 2015 in this case). There, you usually want to display the point in time when the article was first published.

So, how do you get this into the HTML source code of all of your blog posts? A simple solution is to create a custom “byline” (that is what the author and date information string is often called in the context of WordPress themes), for instance with a PHP function like this:

function modbyline() {
    $datecreated = esc_html(get_the_date());
    $author = esc_html(get_the_author());
    $datemodifiedISO = esc_html(get_the_modified_time("c"));
    echo '<div class="bylinemod"><time class="entry-date updated" datetime="'.$datemodifiedISO.'" pubdate>'.$datecreated.'</time> &mdash; by '.$author.'</div>';
}

This creates HTML code for a custom byline, in my case rendered like so:

<div class="bylinemod">
    <time class="entry-date updated" datetime="2015-02-28T18:09:49+00:00" pubdate>
        February 28, 2015
    </time>
    &mdash; by Jan-Philip Gehrcke
</div>

The user-visible date is the article publication date, and the machine-readable datetime attribute encodes the modification time of the article. Note that WordPress’ get_the_modified_time() by default returns a date string with a human-readable default format. In order to make it machine-readable by ISO 8601 standard, you need to provide it the "c" format specifier argument (I have done this in the function above).

You want to define this custom byline function in your (child) theme’s functions.php. It should be called from within content.php.

After inclusion use Google’s structured data testing tool for validation of the approach. It should show updated entry, containing the correct date.

WP-GeSHi-Highlight 1.2.3 released

I have released version 1.2.3 of WP-GeSHi-Highlight. WP-GeSHi-Highlight is a popular code syntax highlighting plugin for WordPress, based on the established PHP highlighting library GeSHi.

The only change in this realease:

  • The bundled GeSHi library was updated to version 1.0.8.12.

So far, there are no official release notes for GeSHi 1.0.8.12. However, the commit history clarifies that this update involves various language file improvements as well as newcomers. A list of those languages that are affected by the update (manually crafted):

  • PHP
  • Rust
  • TCL
  • CSS
  • Haskell
  • PostScript
  • QML
  • NSIS
  • Nimrod
  • Oxygene
  • LSL2
  • StandardML
  • Oxygene

With this update in place, WP-GeSHi-Highlight supports syntax highlighting for 240 languages.

Documentation, FAQ, and comments can be found at gehrcke.de/wp-geshi-highlight.

Official WordPress themes should have an official change log

Officially supported themes: TwentyXXX

My website is WordPress-backed. WordPress front-ends are called “themes”. There are official themes, released by WordPress/Automattic. And there are thousands of themes released by third parties. While the WordPress project has released many themes, not all of them are equally “important”. There is only one specific series of WordPress themes that is so-to-say most official: themes from the TwentyXXX series.

The issue: no update release notes

In this series, WordPress releases one theme per year (there was TwentyEleven, TwentyTwelve, TwentyThirteen, you get the point). The most recent one of these themes is included with every major release of WordPress. In other words: it does not get more official. Correspondingly, themes from this series enjoy long-term support by the WordPress project. That is, they retrieve maintenance updates even years after their initial release (TwentyEleven was last updated by the end of 2014, for instance). That is great, really! However, there is one very negative aspect with these updates: there are no official release notes. That’s horrible, thinking in engineering terms, and considering release ethics applied in other serious open source software projects.

Background: dependency hell

TwentyXXX theme updates are released rather silently: suddenly, the WordPress dashboard shows that there is an update. But there is no official change log or release note which one could base a decision on. Nothing, apart from an increased version number. That is different from updating WordPress plugins, where the change log usually is only one click away from the WordPress dashboard. Also, the theme version number can not be relied upon to be semantically expressive (AFAIK WordPress themes are not promised to follow semantic versioning, right?)

Now, some of you may think that newer always is better. Just update and trust the developers. But that is not how things work in real life. Generally, we should stick to the paradigm of “never change a running system”, unless […]: sometimes, an update might change behavior, which might not be desired. Sometimes an update might fix a security issue, which one should know about and update immediately. Or the update resolves a usability issue. Such considerations are true for updates for any kind of software. But, in the context of WordPress, there is an even more important topic to consider when updating a theme: an update might break child themes. Or, as expressed by xkcd: “Every change breaks someones workflow”:

http://xkcd.com/1172

http://xkcd.com/1172

A theme can be used by other developers, as a so-called parent theme, in a library fashion — it provides a programming interface. This affects many websites, like mine: a couple of years ago I have decided to base the theme used on my website (here) on the TwentyTwelve theme. I went ahead and created a child theme, which inherits most of its code from TwentyTwelve and changes layout and behavior only in a few aspects. I definitely cannot blindly press the “update” button when TwentyTwelve retrieves an update. This might immediately change the interface I developed my child against, and can consequently break any component of my child theme. Obviously, I cannot just try this out with my live/public website. So, I have to test this update before, in a development environment which is not public.

If proper release notes were available, I could possibly skip that testing and apply such an update right away if it’s just a minor one. Or, I would be alerted that there is a security hole fixed with a breaking change in the parent theme, and I’d know that I have to quickly react and re-work my child theme so that I can safely apply the update to the parent. These things need to be communicated, like in any other open source project with a decent release policy.

Concluding remarks

Yes, there are ways to reconstruct and analyze the code changes that were made. This URL structure actually is quite helpful for generating diffs between theme versions: https://themes.trac.wordpress.org/changeset?old_path=/twentytwelve/1.4&new_path=/twentytwelve/1.6. That URL shows differences between TwentyTwelve 1.4 and 1.6. The same structure can be used for other official themes and version combinations. However, this does not replace a proper change log. WordPress is a mature, large-scale open source project with a huge developer community. Themes from the TwentyXXX series are a major component of this project. The project should provide change logs and/or release notes for every update — for compliance with expectations, and for enabling sound engineering decisions. Others want this, too:

Can any one point me to the release notes for 1.2 or a list of the applied changes? Updating from 1.1 has caused some minor, but unexpected presentation changes on one of my child themes, and I’d like to know what else has changed and what to test for before I upgrade further sites.

WordPress Duplicator FTW

When transferring a WordPress instance from a development environment towards the production site I used to manually apply MySQL command line tools for exporting and importing the database, third-party hacks for replacing URLs within the database, and tar and/or scp/rsync for moving files around. This is a pretty straight-forward and reliable work flow.

There is, however, a shining plugin called Duplicator which will simplify these tasks for me (and for you!) in the future and which provides some additional value. It abstracts the process of transferring a website in terms of packages. Package abstractions are used in all kinds of professional applications (think Unix-like operating system distributions, mobile operating systems, programming language extensions, Linux containers, and so on) — I find the idea of WP instance packaging compelling. A Duplicator package contains

  • a file system snapshot, containing all files and directories below the WP root directory
  • a dump of your database
  • a description
  • an installer.php file for deploying the package elsewhere.

Everything but the installer file is automatically archived and checksummed, and gets a proper file name. Eventually, a package is i) a zip file and ii) the installer.php file.

You can create such packages at any point in time from within the dashboard of your running WordPress instance. Packages are stored and indexed, and a list of available packages (created from the current instance) is shown in the dashboard. You can list, download or delete these package at any point in time:

duplicator_interface

For transferring your WordPress instance to another environment, you would transfer both package files to the new location (both go to the same directory) and execute installer.php. At this point in time you need to provide the credentials for the (new) database connection. Furthermore, the install script shows the auto-detected “old URL” and “new URL” of your WordPress instance. When you invoke installation, Duplicator will replace occurrences of the old URL in your database with the new one. It also takes care of adjusting your wp-config.php. In case your .htaccess files needs to be updated in the new location, Duplicator will provide you with instructions how to do so. After that, you are usually done: a new WP instance is up and running, with the same contents as snapshotted before during package creation.

All in all, Duplicator provides a very convenient WP instance packaging solution, as well as all required tools for safely transferring a WP instance to another environment. It is actively developed and supported, and its GUI in the dashboard as well as the installer GUI make a clean impression.

Obviously, Duplicator also serves as a nice one-button-press all-in-one backup solution before performing risky tasks (Just do not forget to download the package! :)).

There is just too much plugin trash out there, and Duplicator for sure is one of those plugins that stand out by usability and professionalism.