My main goal when building tollmanz.com was to ensure that the content would always be pleasant to read. I really enjoy the “read later” services and modelled my theme off of those services’ easy-to-read article templates. Before launching, I also knew that I would need to focus a lot of attention on making code easy to read. I believe I have accomplished this with what I call “Pretty Cacheable Gists”, which is some code I wrote to utlize Gists for code snippets that are served locally, but processed with GitHub’s wonderful Gist service.
Pretty Cacheable Gists has allowed me to accomplish my goals for displaying code snippets, which are:
- Served locally
- Cache friendly
- Pretty syntax highlighting
- Easy to contribute to and comment on
How It Works
Pretty Cacheable Gists looks for Gist links when a post is saved. If a Gist is detected, the ID for the Gist is obtained and added to a list of Gist IDs to be processed. The script only queues Gists that are not already stored locally for processing. Additionally, the function that processes that list is queued to be executed ASAP with a WordPress scheduled event. I use the method of processing on a scheduled event to avoid slowness when the updating or saving a post.
When the WordPress scheduled event for processing Gists executes, it does a number of things. First, it pings the Gist API to get all of the information about the Gist. I only save pieces of information relevant to my use. Second, I ping the JSON endpoint for the processed Gist code. Interestingly, the Gist API provides you with only the raw code. The JSON endpoint give you the processed Gist, which wraps different parts of the code in
div elements for styling. Because I want Gists with a nice syntax highlighting, this is especially important. Finally, the Gist information is saved as a new post of “cgist” post type. After this completes, the Gist is stored locally and I no longer have to depend on the Gist service for my code snippets.
This is not a Plugin
I contemplated releasing this code as a plugin; however, I opted to only release the code and specifically not think of it as a plugin. There are a lot of Gist plugins for WordPress in the repository that I am sure satisfy a lot of people’s needs. I created these cacheable Gists for my purpose and my purpose only. There are a lot of things it cannot handle (e.g., multiple files in a Gist, no styling for other languages, comments). Additionally, if I released this as a plugin, I would be compelled to save each version of the Gist, allow for updating/creating Gists from WordPress, allowing different views for the Gist, etc. Basically, I feel that I would need to do a lot more work before releasing it as a plugin and a lot of the features I do not have an interest in. As a result, I am simply making the code available as a Gist. This way, others can have the code and I do not feel responsible for creating and maintaining a plugin. I would be very happy for someone else to pick up the code and make a plugin out of it.