Most lightweight, yet most configurable and advanced PrismJS WordPress integration plugin. Custom fields display (detached) supported.

Despite two plugins already on wordpress.org I decided to write my own from scratch. The result is a very capable minimalistic plugin with only ~250 lines of PHP.

  • Supports every possible Prism configuration.
  • Does not load prism on every page, only when needed.
  • Supports automatic detection of prism HTML.
  • Supports displaying code from custom fields with [[prism]] shortcode.
  • Developers may use the prism handle to enqueue the pre-registered script and style.
  • Has admin editor button for quick shortcode template snippet.
  • Has no options page by design.

Whats PRISM?

PRISM is a clandestine mass electronic surveillance data mining program launched in 2007 by the National Security Agency (NSA), with participation from an unknown date by the British equivalent agency, GCHQ. PRISM is a government code name for a data-collection effort known officially by the SIGAD US-984XN. The Prism program collects stored Internet communications based on demands made to Internet companies such as Google Inc. under Section 702 of the FISA Amendments Act of 2008 to turn over any data that match court-approved search terms – damn wrong text, sorry lets start over:

Prism is a is a lightweight, extensible syntax highlighter, written in JavaScript and CSS by code pirate Lea Verou built with modern web standards in mind.

How Does it Work?

  • Show code from custom fields with [[prism field=my_custom_field_name language=php]] shortcodes.
  • Show code from any URL with [[prism url=http://some.file.to/show.css language=css]]. For example a Gists or files on Github but remember it has to be the raw URL or you will get the HTML or the entire Github page! This is a way more flexible alternative to prisms file-highlight plugin (data-src) because of this: “Please note that the files are fetched with XMLHttpRequest. This means that if the file is on a different origin, fetching it will fail, unless CORS is enabled on that website.”
  • Write the normal prism HTML inside your post content, this plugin automatically detects when <code class="language- is used in your content, and will load prism only then.

Thanks to Jannik Zschiesche and his Prism Detached plugin for introducing me to this great idea. The plugin seems not to be maintained, and considered the code bloated so I wrote this from scratch.

Why is the ‘Detached’ Idea so Great?

When dealing with code inside the WordPress TinyMCE things can get messy fast. WordPress loves reformat code and things like that. I was never comfortable with it. But if you handle the code inside custom fields you always know WordPress will not touch it, you also can type HTML entities like < directly in there without the need for them being escaped unlike when using the code editor. This is also incredibly helpful when it comes to line numbers since you may combine this with another plugin that lets you display custom meta boxes for custom fields as a code editor. I have tried Advanced Custom Fields with the Code Area Addon but it requires you to predefine languages and fields ids to display a Codemirror box. I am sure there is a even better solution. If you know one, please let me know.

How to configure it?

This is the the great part: You head over to prismjs.com/download.html select what you like included and store the prism.js and prism.css files inside a prism folder (you have to create it) inside your WordPress upload folder.

.../wp-content/uploads/prism/prism.js + .css on single site WP installs + main site for multisite

.../wp-content/uploads/sites/<site_id>/prism/prism.js + .css for sites on a multisite install

This plugin will detect your prism version and load it, if not present it will load its bundled default version.

Where is the Options Page?

There is none by design, please read the above again 😉

Shortcode usage

Shortcode attr. Usage
field id of the custom field to be used. This is needed with exception when data_src is used
post_id optionally take the custom field from another post
url display a file from any URL catched with wp_remote_get()
language will end up as language-xxx class on the <code> element (<pre> when data_src is used)
Shortcode attr. <pre> attributes, same as the shortcode except underscores become dashes
id defaults to same value as field, only set if you need something different
class add any class for example line-numbers to use the line-numbers plugin
data_line data-line for line-highlight plugin
data_line_offset data-line-offset
data_start data-start
data_src data-src for use of the file-highlight plugin
data_manual always data-manual without value no matter what value you set

Examples

Show custom field prism_css_demo with some CSS

[[prism field=prism_css_demo language=css]]
[prism field=prism_css_demo language=css]

Line numbers

[[prism field=prism_php_demo language=php class=line-numbers]]
[prism field=prism_php_demo language=php class=line-numbers]

Line highlight (note that I specified a ID since I used the same field I already used above, else I would end up with invalid HTML on this page because it would use the ID 2 times)

[[prism field=prism_php_demo language=php id=prism-data-line-demo data_line=2-4,7-10]]
[prism field=prism_php_demo language=php id=prism-data-line-demo data_line=2-4,7-10]

Show this plugins code from Github. Set id to use line highlighter triggered by URL

[[prism url=https://raw.githubusercontent.com/nextgenthemes/prism/master/prism.php language=php id=github-file-demo]]
[prism url=https://raw.githubusercontent.com/nextgenthemes/prism/master/prism.php language=php id=github-file-demo]

Link to #github-file-demo.50-55,60 will trigger file-highlight above.

Activate archive scan

If you want to use prism HTML and have a theme that displays the full page content on archives you can define( 'PRISM_ARCHIVE_SCAN', true ); in a mu-plugin or in your themes functions.php and this plugin will scan all current displayed posts for <code class="language- on archive pages and will load prism there if needed. If you use shortcodes to display fields this is not needed.

Make it load in other places/everywhere

This plugin registers the prism script and style with the prism handle, you can use this for your purposes. For example like this:

[prism field=prism_load_example language=php]

Limitations

WordPress theme styles might be overwriting prisms styles for the Twentytwelve theme for example I needed to add …
[prism field=fix2012css language=css]
… to your CSS or the line highlight will get out of sync. I also had to add !important to the paddings rules for pre. This is already included in the bundled CSS, see the CSS file above.

On archive pages with infinite scroll the prism detection will not work for posts that load up later. If none of the initial displayed posts has <code class="language-"' or the [[prism]] shortcode in it, prism will not be loaded. You might use your own function and load or on all archive pages if you need this edge case.

Note

  • There is no HTML language in prism, use markup.
  • I am not the author of prism.js, this is the wrong place for any issues … related to prism. Only for this integration plugin.

The NOT to do list

  • No translation planned
  • No more features planned