GistPress3

Contributors: tychay, Brady Vercher, Gary Jones
Requires at least: 3.5.0
Tested up to: 4.1.1
Stable tag: trunk
License: GPL-2.0+
tags: gist, oembed, gistpress

Extend Wordpress to create a bidirectional embed Gists via oEmbed or shortcode.

Description

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.

###Features###

• 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.

In addition GistPress3 adds the following:

• Backwardly compatible with JetPack/WordPress.com-style shortcodes
  • bare url in attributes
  • id in content
  • url in content
• Allows arbitrary content to be put in shortcode (and removed in output)
• Disable JetPack and oEmbed Gist plugin handling by default
• Support for url###"" substitute for id###"" in shortcodes (oEmbed Gist-style)
• Non-parsed gist shortcodes are simply passed through (adds a comment)
• Supports revision sha1 linking, alsoo through revision="" in shortcode
• Settings page (with help tab) in Admin for configuring defaults.

TODO:

• Support for "gistpress" shortcode via API upload

Installation

Warning

You cannot have GistPress and GistPress3 installed and active at the same time as the function and class names overlap.

Installing the Plugin

Automatic:

1. Choose Plugins > Add New…
2. Search for "GistPress"
3. Click on "GistPress3"
4. Click "Install Now"

Upload:

1. Download the latest release from GitHub.
2. Go to the Plugins → Add New screen in your WordPress admin panel and click the Upload tab at the top.
3. Upload the zipped archive.
4. Click the Activate Plugin link after installation completes.

Manual:

1. Download the latest release from GitHub.
2. Unzip the archive.
3. Copy the folder to /wp-content/plugins/.
4. 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.

Git:

1. Navigate to /wp-content/plugins/
2. Clone repository: git clone git@github.com:tychay/gistpress.git
3. Go to the Plugins screen in your WordPress admin panel and click the Activate link under GistPress.

Updating

Automatically installed plugins can be updated via the "Automatic" method above.

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, there are a couple of options you can install to manage updates from GitHub-hosted plugins:

• Git Plugin Updates
• GitHub Updater

###Using the plugin###

####oEmbed####

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.

####Shortcode####

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"]

Shortcode Attributes

Attribute	Description	Example
id	A Gist ID. Required. Secret Gist IDs work, too.	4204333
url	Can be used in place of id, file, and revision. Required if id is misssing.	https://gist.github.com/padolsey/527683
file	A filename in a Gist. Required when using the following attributes with a multi-file Gist.	filename.php
revision	Allows linking of specific revision instead of latest	eea6004e74dfd42a63cc3b46e1412a3c8d5bb680
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.

Screenshots

Example Gist embed with line number restrictions, a highlighted line, and meta links disabled.

Notes

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.

Highlighting

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' );

Caching

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.

Changelog

Version 3.0

• First release of GitPress3 (bi-directional support)
• oEmbed supports revision sha1's
• Shortcode attributes supports: bare url (Jetpack-style), url (oEmbed Gist-style), and revision
• Shortcode content supports: bare url & id (Jetpack-style), arbitrary stuff to ignore (Gangnam-style)
• Plays nice/mean with similar plugins: disables JetPack, oEmbed Gist
• New Settings page (with help) added: set defaults.
• Numerous small bugfixes, refactors and other improvements

Version 2.03

• Forked from 2.03 built by Brady Vercher & Gary Jones. See Changelog