WordPress Plugin Review: GitHub README

photo-1429051883746-afd9d56fbdaf

If you’re a developer and anything like the people here at Delicious Brains, you’ve likely got a whole bunch of open source repositories on GitHub, some of which you want to promote on your personal or company site. Wouldn’t it be cool to use your meticulously maintained README from GitHub for the page contents of your WordPress site and have it update automatically when you push changes to the README? Well, let me introduce you to GitHub README by Jason Stallin.

Setup

It doesn’t get much easier than this really, from the WordPress dashboard go to Plugins > Add New and then search for “GitHub README”.

GitHub README - Add Plugins

The information for the GitHub README plugin is sparse and to the point.

GitHub README - Plugin Info

Click the Install button and then activate. That’s it, there’s nothing else needed in the admin area. All configuration is through the github_readme shortcodes provided by the plugin.

Simple Usage

The simplest way to use GitHub README is to add the shortcode to a page or post, specifying the repository that has the readme.

GitHub README - New Page

In the above screenshot I simply added the following shortcode to a new page in order to show the readme for Amazon Web Services.

[github_readme repo="deliciousbrains/wp-amazon-web-services"]

Once published, magic happens…

GitHub README - Simple Usage

GitHub README has retrieved the default readme for the deliciousbrains/wp-amazon-web-services repository.

But, alas, WordPress has its own title of “Amazon Web Services” shown on the page, followed by the exact same title coming from the readme, not ideal.

Trim

GitHub README has a nifty feature to combat this problem of repeated content in retrieved readme files, you can “trim” the beginning of the readme.

Let’s trim off the title from the fetched readme, as well as WordPress plugin specific tags that don’t fit well in a page to promote the work.

[github_readme repo="deliciousbrains/wp-amazon-web-services" trim="7"]

That trim="7"is all that is needed to remove the first seven lines from the readme when it is embedded in the page.

GitHub README - Trim

This also means it plays nicely with the “more tag”. In this example we could trim off the short description and use it for the excerpt with addition of items not found further down the readme.

Houses the Amazon Web Services (AWS) PHP libraries and manages access keys. Required by other AWS plugins.

<a href="http://opensource.org/licenses/GPL-2.0"><img src="https://img.shields.io/badge/license-GPL--2.0%2B-green.svg" alt="License" /></a>

<!--more-->

[github_readme repo="deliciousbrains/wp-amazon-web-services" trim="10"]

GitHub README - Trim & More

Other Markdown

Sometimes you want to embed GitHub documentation other than the default readme into your WordPress site; GitHub README can do that with the new github_markdown shortcode introduced in v0.1.

With the github_markdown shortcode you can import a specific file using the file attribute, and still use the trim feature. There’s also a cache attribute you can use to specify the number of seconds that the content should be cached (in a transient record).

Let’s add a “Contributing” sub-page to our Amazon Web Services example.

[github_markdown repo="deliciousbrains/wp-amazon-web-services" file="CONTRIBUTING.md" trim="2" cache="10"]

In the above code I’m embedding a file call “CONTRIBUTING.md” that is found in the root of the repository, if a file is in a sub-directory you just include it in the file attribute.

While impatiently checking some changes to the doc in WordPress I set the cache value to a very low 10 seconds in the code above, I wouldn’t use something as low as 10 seconds normally. The default cache time for github_markdown is 60 seconds, whereas github_readme is hard-coded to 12 hours per combination of repo and trim setting.

GitHub README - Markdown

The github_markdown shortcode also supports a branch attribute, which is very useful if you would like to display a document from a particular branch that isn’t set as the default on GitHub.

Wiki Pages

So, we have the default readme and any Markdown formatted files covered, how about those wiki pages then?

Well, of course GitHub README has you covered there too, with the github_wikipage shortcode and its page attribute. It also supports the trim and cache attributes, cache defaults to 60 seconds.

[github_wikipage repo="deliciousbrains/wp-amazon-web-services" page="AWS-SDK-Update-Process"]

GitHub README - Wiki

The Code

I took a peek at the code. As you might expect, the bulk of the code is in a PHP Markdown library that is kept in a separate sub-directory. Otherwise it’s a single PHP file with three calls to register the new shortcodes along with their respective handler functions.

The first thing that jumps out is the use of extract(), which is discouraged in the WordPress PHP Coding Standards, for good reason. I personally dislike extract, as convenient as it is, it makes your code unintuitive, hard to debug, and plain makes IDEs cry.

GitHub README - Extract

There are a couple of other WordPress coding standards faux pas. Indentation is with spaces rather than tabs, spaces aren’t used properly around arguments, conditions and operands, and braces are hanging instead of end of line for function declarations and if statements. There’s a few instances of non Yoda conditions, and also no PHP Doc blocks. All pretty innocuous stuff and easy to fix.

The code is pretty straight forward and easy to read which is nice, there’s very little in the way of overly clever code which always makes code easy to pick up when you return to it or come across it for the first time. Although code like the following always catches me out and leaves me hunting for where the variable was assigned…

if ( false === ( $html = get_transient($transient))) {

I always prefer…

$html = get_transient( $transient );
if ( false === $html ) {

I’d personally be checking the results of the cURL calls and json_decode(), though I’m quite a defensive coder.

It’s a shame that the shortcodes aren’t supplied to the shortcode_atts() functions. It would be handy to use the shortcode_atts_{$shortcode} filter to apply default attributes (such as a smaller cache time or default branch) when using the plugin on a development site without having to add those to every use of the shortcodes.

Feature Requests

There are a couple of things I’d like to see added to GitHub README:

  • cache attribute added to the github_readme shortcode.
  • branch attribute added to the github_readme shortcode.
  • The ability to use the shortcode_atts_{$shortcode} filter.

It would also be good to fix the github_markdown and github_wikipage transients so they properly reflect changes in the applied shortcode attributes.

I’ve raised a PR for these features and fixes as well as a general cleanup.

Conclusion

GitHub README is a great little plugin that does exactly what it says it will, with no fuss and no fanfare. It’s one of those small, useful plugins, that could easily get lost within the myriad of similar plugins on the WordPress.org Plugins Directory, but definitely deserves a look if you want a free and easy way of making use of your GitHub content on your site.

What other GitHub related plugins do you find irreplaceable? Let us know in the comments below.

About the Author

Ian Jones

Ian is always developing software, usually with PHP and JavaScript, loves wrangling SQL to squeeze out as much performance as possible, but also enjoys tinkering with and learning new concepts from new languages.