A WordPress plugin to easily embed Gists via oEmbed or shortcode.
Contributors: Brady Vercher, Gary Jones
Requires: 4.0
Tested up to: 4.3
License: GPL-2.0+
GitHub provides a method for embedding Gists on websites, but it requires inserting a <script> tag, which can become mangled or stripped from the TinyMCE editor used in WordPress. Instead, this plugin allows you to embed a Gist by simply inserting its URL into the editor for oEmbed-like support, or via a shortcode for more refined control.
- Better integration with the visual editor in WordPress since
<script>tags aren't used, which also allows visitors without JavaScript to view your code snippets. - Users viewing your content in a feed reader will see a link directly to the Gist instead of nothing.
- Limit which lines from a Gist are displayed. Helpful for breaking down code so it can be easily explained.
- Highlight specific lines within a Gist to call attention to them.
- Easily debug embedded Gists using a custom panel for the Debug Bar plugin.
- A few additional CSS classes are inserted for better styling hooks.
Example Gist embed with line number restrictions, a highlighted line, and meta links disabled.
Embedded Gists are cached using a custom algorithm that minimizes HTTP requests and ensures your code snippets continue to display even if GitHub is down. If you need to update the snippet with changes made on GitHub, just update the post and the cache will be refreshed.
If you decide you don't want to use the plugin, simply uninstall using the "Delete" link on the Plugins screen, and all cached data and options will be cleaned up. Like it never even existed.
- Download the latest release from GitHub.
- Go to the Plugins → Add New screen in your WordPress admin panel and click the Upload tab at the top.
- Upload the zipped archive.
- Click the Activate Plugin link after installation completes.
- Download the latest release from GitHub.
- Unzip the archive.
- Copy the folder to
/wp-content/plugins/. - Go to the Plugins screen in your WordPress admin panel and click the Activate link under GistPress.
Read the Codex for more information about installing plugins manually.
Clone this repository in /wp-content/plugins/:
git clone git@github.com:bradyvercher/gistpress.git
Then go to the Plugins screen in your WordPress admin panel and click the Activate link under GistPress.
Although it's not a regular occurrence, GitHub may introduce new features or changes that break the way this plugin works. In such cases, it's important to receive notifications and be able to easily update with the latest fixes. Fortunately, you can install the GitHub Updater plugin to manage updates from GitHub-hosted plugins.
Insert the URL to a Gist on its own line like this (don't link it up):
https://gist.github.com/9b1307f153f4abe352a4
That's it!
Notice that URL is for a secret Gist? Of course URLs for public Gists work, too.
Using the same URL from above, the shortcode equivalent would look like this:
[gist id="9b1307f153f4abe352a4"]
In both cases, that will embed all four files in the example Gist, however, with the shortcode, you have the option to limit the display to a single file by specifiying its name:
[gist id="9b1307f153f4abe352a4" file="media-control-snippet.php"]
Taking it further, you can limit display to specific lines within a file:
[gist id="9b1307f153f4abe352a4" file="media-control-snippet.php" lines="2-5"]
Or even highlight lines:
[gist id="9b1307f153f4abe352a4" file="media-control-snippet.php" highlight="7"]
| Attribute | Description | Example |
|---|---|---|
id |
A Gist ID. Required. Secret Gist IDs work, too. | 4204333 |
file |
A filename in a Gist. Required when using the following attributes with a multi-file Gist. | filename.php |
highlight |
Comma-separated list of lines or line ranges to highlight. | 1,5-10,13 |
highlight_color |
The highlight color. A filter is provided for changing globally. | #ff0000 |
lines |
The range of lines to display. | 2-10 |
lines_start |
Number to start lines at. | 543 |
show_line_numbers |
Whether line numbers should be displayed. Defaults to true. | 0 to disable. |
show_meta |
Whether the meta links following a Gist should be displayed. Defaults to true. | 0 to disable. |
Some themes may include styles that interfere with the default rules for embedded Gists. You can override the conflicting styles in your theme's (or child theme's) style sheet with more specific rules targetting the embed HTML. Typically, this might include removing margins on <pre> elements, changing padding on the table cells, and ensuring the line-height and font-size properties for line numbers and code match so they align properly.
To support line highlighting, an inline style is added by the plugin, however, a class is also added to the line element. Developers can add a CSS rule similar to the following to their theme style sheet in order to change the color:
.line-highlight {
background-color: #ffc !important;
}And the following would go in the theme's functions.php to disable the style attribute.
add_filter( 'gistpress_highlight_color', '__return_false' );See CHANGELOG.
Built by Brady Vercher & Gary Jones