Skip to content

Latest commit

 

History

History
168 lines (120 loc) · 6.94 KB

README.md

File metadata and controls

168 lines (120 loc) · 6.94 KB
Raw

GistPress

A WordPress plugin to easily embed Gists via oEmbed or shortcode.

Contributors: Brady Vercher, Gary Jones
Requires: 4.0
Tested up to: 5.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.

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.

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

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.

Installation

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

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.

Updating

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.

Usage

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

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

Changelog

See CHANGELOG.

Credits

Built by Brady Vercher & Gary Jones