Embedding source code in WordPress isn’t an easy task. Although few plugins have tried to simplify this task of sharing and embedding codes, it’s easy to get the code messed up with other text and content in the WordPress editor.
Wouldn't it be awesome if we could directly embed the code snippets from Gist using oEmbeds?
In this post, I will walk you through few ways that you can easily embed GitHub Gists in WordPress posts. I will also show you some additional controls and options with Gist that you can achieve by installing different plugins.
First, if you have stumbled on this article and do not know idea about Gist, here’s a brief introduction to the code snippet service – Gist.
Table of Contents
GitHub Gists Introduction
Gist is a service from Github that allows you to share your git repositories with all the functions of Github. You can add your chunk of codes to a Gist and share it anywhere you like.
GitHub introduces gist as a Git repository that can be forked, cloned, and manipulated in every way.
The introduction is pretty self-explanatory, and if you’ve used Github before, it won’t take you long to understand and start using Gist.
Embedding Gists in WordPress
As Gists have become a popular way of sharing codes, there exist many ways you can embed it within your WordPress post.
GitHub itself provides a default way to embed Gist in other websites, and it requires inserting a “script” tag. But like I mentioned above inserting codes with “script” tags can get messed up with the TinyMCE editor used in WordPress.
Plugins or some custom code that enables oEmbeds for Gist should be an ideal solution. Let’s get started with the easiest one – Adding oEmbed support using plugins.
Embedding Gist Using Plugins
1. Shortcode Embeds – Jetpack Plugin
If you use the popular Jetpack plugin, you can just activate the Shortcode Embeds feature to add oEmbed and shortcode support for several platforms including Gist.
First activate Shortcode Embeds feature by navigating to Jetpack > Settings > Shortcode Embeds.
Once activated, let’s look into few ways you can embed Gists using the shortcode embeds feature of Jetpack plugin.
1.1 Using oEmbeds – Sharing URL directly
Jetpack supports oEmbeds for Gists, which makes it really easy to share them within your posts or pages.
To embed any specific Gist, all you have to do is copy the URL of the gist and paste it into a single line.
- First copy the URL as you can see in the URL bar.
- Paste it on a single line of its own in WordPress editor.
This should automatically pull in the gist and make it embedded into your post or page – wherever you are looking to display the Gist.
Note: please make sure you do not turn the URL into a link.
1.2 Using Shortcodes to Embed Gist
Shortcodes allow greater flexibility of where and how you can display the Gist in your blog.
If you prefer using Shortcodes within post/page editor, you will need to;
i) Find and copy the URL of the Gist that you want to embed
ii) Put it in a format like this Shortcode
iii) Alternatively, just use the number part in the URL to embed it in this format.
2. GistPress Plugin
GistPress allows you to add oEmbed support and Shortcodes to embed Gists similar to Jetpack feature discussed above.
In addition to providing all features of Jetpack Shortcode embeds, GistPress provides some additional features that might be useful if you are looking to customise further how Gist appears on your blog.
Some notable additional features of the plugin include,
- Ability to display only specific lines from the gist that can be useful if you are explaining lines from your code.
- Ability to highlight specific lines within a Gist.
- Ability to add additional CSS classes for better styling.
GistPress is also built with developers in mind, allowing you to add CSS styling hooks and advanced features such as letting you debug embedded Gists using a custom panel for the Debug Bar plugin.
2.1 Using oEmbeds with GistPress
This is straightforward. All you have to do is paste the URL to a Gist in a single line in the WordPress editor.
2.2 Using Shortcodes for additional features
The advantage of using Shortcodes over oEmbeds is that you can further customise the way Gists appear in your post.
a. General Shortcode
The shortcode includes id of the Gist file, just make note of the syntax.
b. Displaying only single files
By default, both oEmbeds and general shortcode above will display all the files in the Gist (Yes, a Gist could be a combination of multiple files – Multi-Gist).
You can further specify the name of the file in shortcode to display the single file.
c. Display specific lines from a Gist File
You can further limit tot display only a specific line from a file. Add the lines attribute to the shortcode and specify the range of lines (see the shortcode below).
d. Highlight lines of a Gist File
Just add highlight attribute and specify a comma-separated list of lines or line ranges to highlight from the gist file.
There are few more shortcode attributes mentioned in the documentation that you can use to customise your Gist’s appearance.
With plenty of options and unique features, GistPress is a complete plugin to integrate Gists with WordPress.
The only downside that I see with the plugin is that it’s hosted on GitHub and not available on WordPress plugin repository. This can make it difficult to manage updates for the plugin.
You can, however, install the GitHub Updater plugin that allows you to manage updates from GitHub-hosted plugins such as GistPress.
3. WP Gist Plugin
The plugin only allows to use the add Gist embeds using Shortcode in your post or page (Note that above plugins – GistPress and JetPack both allow easier method of simply enabling oEmbeds).
The only difference with WP Gist that makes me include the plugin here is its adjusted style that makes it look good with almost any theme.
Embedding Gists with WP Gist
Please make note of the syntax in shortcodes that you will need to embed Gists.
3.1 Single/Complete Gist
To embed a Gist, simply use the [wpgist] shortcode with the id of the Gist you want to embed.
3.2 Specific File within a Multi-File Gist
You can specify to display only a single file from a multi-file gist by adding a file attribute.
[wpgist id="5014426" file="find-this-line-in-load-styles.php"]
Similar to GitPress, you will need to use GitHub Updater plugin for automatic updates as the plugin is only hosted on GitHUb.
You can check out the GitHub project page for further usage instructions or if you want to contribute to the plugin.
4. oEmbed Gist
oEmbed Gist is a simple plugin that lets you add oEmbed support for Gist files. The plugin is available for free on WordPress plugin repository. You can also search and install the plugin from your WordPress dashboard.
Once installed, there are two ways that you can embed Gists using this plugin.
a. Gist URL on single Line
Simply paste the URL of the Gist on a single line.
b. Individual File from Multi-File Gist
To embed an individual file that is part of a multi-file Gist, make sure you include the specific file selector to the end of the URL.
So, far we discussed ways that you can use plugins to add Gists in different ways. Although I strongly recommend using above plugins, you can easily add oEmbed support by adding few lines of custom code to your theme.
Custom Code to Add Gist Support
Here’s a custom code that you can code to your theme’s function.php file (use Child Theme and always backup your file) or use as a plugin.
As you can see in the Gist file embedded below (using oEmbeds), the code is from Ninnypants.
You can find several other custom codes by searching for it, but I suggest sticking to the above plugins if you are not an advanced user.
I hope you are now familiar with GitHub Gists and ready to share your code snippets with Gists. We should hopefully see support for Gist oEmbeds by default in WordPress core soon!
What platform or plugin do you use to share your code snippets?