This page continues the Installation & Usage instructions from the plugin’s homepage at WordPress.org.
The Prismatic plugin follows the same conventions used by Prism.js and Highlight.js. Here are the basic steps:
Once the settings are configured, you can enable syntax highlighting for any code snippet by doing one of the following:
<pre><code>...</code></pre>
<code>...</code>
The plugin also provides a Prismatic Gutenberg block and TinyMCE buttons. So you can add code snippets with a few clicks easily.
Note: Prism.js highlights both multi-line and single-line code snippets. Highlight.js only supports multi-line code snippets.
With the proper markup in place, you can indicate a specific language by adding a class of language-abc
or lang-abc
to the <code>
tag (where abc
is the language identifier).
For example, to indicate PHP as the language for a single-line code snippet:
<code class="language-php"><?php echo 'Hello world'; ?></code>
Likewise, to indicate HTML as the language for a multi-line code snippet:
<pre><code class="language-html"> <table> <tr> <th>Name</th> <th>Side</th> <th>Role</th> <tr> <td>Darth</td> <td>Dark</td> <td>Sith</td> </tr> </table> </code></pre>
Alternately, the language class may be placed on the <pre>
tag, for example:
<pre class="language-html"><code> <table> <tr> <th>Name</th> <th>Side</th> <th>Role</th> <tr> <td>Darth</td> <td>Dark</td> <td>Sith</td> </tr> </table> </code></pre>
Basically, the prefix of the class names (i.e., lang-
or language-
) are the same for Prism.js and Highlight.js.
The difference is the language identifier (e.g., css
or html
) used to specify each language.
Check out the following “About Prism.js” and “About Highlight.js” sections for more information.
Note: In addition to detecting the language-
and lang-
prefixes, Highlight.js also will try to
auto-detect the language without it being specified. Plus as an option, you can enable the Highlight.js setting, “Support no-prefix class names”
to enable use of language identifiers without any language-
or lang-
prefix.
Just like Prism.js and Highlight.js, the Prismatic plugin follows HTML coding standards. To enable code escaping:
<pre><code>...</code></pre>
<code>...</code>
For example, the code snippets included in either of the following markup examples would be escaped (note that the class attribute is not required for code escaping).
This is a single-line example:
<code class="language-php"><?php echo 'Hello world'; ?></code>
This is a multi-line code example:
<pre><code class="language-html"> <table> <tr> <th>Name</th> <th>Side</th> <th>Role</th> <tr> <td>Darth</td> <td>Dark</td> <td>Sith</td> </tr> </table> </code></pre>
So what exactly happens when the “Code Escaping” options are enabled? Here is a summary that applies to each section (post content, excerpts, and comments):
Note: Each library — Prism.js, Highlight.js, and Plain Flavor — features its own code-escape settings. So the code-escape settings that are applied depends on the currently active library. Visit the plugin’s General Settings to choose your library. Then visit that library’s tab to configure its code-escape settings.
When code escaping is enabled for either/both the frontend or Admin Area,
the plugin makes the following changes to any code contained within <code></code>
tags:
&
amp;
&
lt;
&
gt;
&
quot;
&
#039;
These are the only changes made to your code, no other changes are made.
As mentioned, the difference between code escaping on the frontend vs. the Admin Area is that, on the frontend, the above changes are made at runtime and not saved to the database; whereas in the Admin Area, the changes are made when the code is viewed via a content editor, such that any changes made will be saved to the database when the user clicks the “Update” or “Publish” button. Please keep this in mind when choosing your code-escape settings.
Important: As explained, enabling code escaping in the Admin Area may result in the escaped code getting saved in the database. This is fine in most cases, but there may be situations where escaping should only happen at runtime. If that is the case, or if you are unsure, choose the “Frontend only” option for the “Code Escaping” setting. The “Frontend only” option only modifies code when displayed on the frontend and does not save any changes to the database.
To highlight a code block using Gutenberg:
To highlight code using the TinyMCE/Visual/Rich-Text Editor:
<>
)There also is a Prismatic Quicktag button (named pre
) for those using the Plain-Text editor.
Prismatic includes several plugins for Prism.js. You can enable them in the Prism settings. Note that some plugins require action on your part, like adding a class to pre elements. Here is a quick list with links to more information.
data-line
attribute to the pre elementline-numbers
class to the pre elementcommand-line
class to the pre elementTo add your own extra CSS classes using the Gutenberg Block Editor, add them to your code block like so:
After these steps, an “Advanced” panel will appear in the sidebar. Toggle it open to find “Additional CSS class(es)”. There you can add any extra classes to your code block (like for Line Numbers or Command Line).
Prism.js version used in Prismatic plugin: 1.29.0
Prism: Lightweight, robust, elegant syntax highlighting MIT license https://www.opensource.org/licenses/mit-license.php/ @author Lea Verou https://lea.verou.me
Language Class Apache = apacheconf AppleScript = applescript Arduino = arduino AVR Assembly = asmatmel Bash = bash Batch = batch C = c C# = csharp C++ = cpp C-like = clike CoffeeScript = coffeescript CSS = css D = d Dart = dart Diff = diff Elixir = elixir G-code = gcode Git = git Go = go GraphQL = graphql Groovy = groovy HCL = hcl HTML/XML/Etc. = markup, html, xml, svg, mathml, ssml, atom, rss HTTP = http Ini = ini Java = java JavaScript = javascript JSON = json JSX = jsx Julia = julia Kotlin = kotlin LaTeX = latex Liquid = liquid Lua = lua Makefile = makefile Markdown = markdown Markup = markup Matlab = matlab NGINX = nginx Objective-C = objectivec Pascal = pascal Perl = perl PHP = php PowerQuery = powerquery PowerShell = powershell Python = python R = r Ruby = ruby Rust = rust SAS = sas SASS = sass Scala = scala SCSS = scss Shell Session = shell-session Solidity = solidity SPARQL = sparql Splunk SPL = splunk-spl SQL = sql Swift = swift TSX = tsx Turtle = turtle Twig = twig TypeScript = typescript Verilog = verilog VHDL = vhdl Vim = vim Visual Basic = visual-basic YAML = yaml
I’m happy to add more languages, make a suggestion.
So for example, to specify a code block as C++, you would write:
Single line: <code class="language-cpp">...</code> Multi-line: <pre><code class="language-cpp">...</code></pre> Alternate: <pre class="language-cpp"><code>...</code></pre>
To disable Prism.js syntax highlighting for any snippet, simply omit the language class.
Or, to disable syntax highlighting for a code snippet while also loading the Prism.js stylesheet, add a class of language-none
, for example:
<code class="language-none">...</code>
Highlight.js version used in Prismatic plugin: 11.7.0
Syntax highlighting with language autodetection. Copyright (c) 2006, Ivan Sagalaev https://highlightjs.org/ All rights reserved. BSD3 License @ https://git.io/hljslicense
Language Class .properties = properties Apache Conf = apache, apacheconf AppleScript = applescript, osascript Arduino = arduino AVR Assembly = avr Bash = bash, sh, zsh C = c, h C# = cs, csharp C++ = cpp, c, cc, h, c++, h++, hpp CSS = css CoffeeScript = coffeescript, coffee, cson, iced D = d Dart = dart Diff = diff, patch Elixir = elixir G-code = gcode, nc GML = gml Go = go, golang GraphQL = graphql Groovy = groovy HTML/XML/Etc. = xml, html, xhtml, rss, atom, xjb, xsd, xsl, plist HTTP = http, https JSON = json Java = java, jsp JavaScript = javascript, js, jsx Julia = julia, julia-repl Kotlin = kotlin LaTeX = tex Less = less Lua = lua Makefile = makefile, mk, mak Markdown = markdown, md, mkdown, mkd Matlab = matlab Nginx = nginx, nginxconf Objective-C = objectivec, mm, objc, obj-c PHP = php PHP Template = (unknown, see note* below) Perl = perl, pl, pm Plaintext = plaintext, txt, text PowerShell = powershell, ps Python = python, py, gyp Python REPL = python-repl, pycon R = r Ruby = ruby, rb, gemspec, podspec, thor, irb Rust = rust SAS = sas Scala = scala SCSS = scss Shell Session = shell SQL = sql Swift = swift TOML/INI = toml, ini TypeScript = typescript, ts VB.Net = vbnet, vb Verilog = verilog, v VHDL = vhdl Vim Script = vim WebAssembly = (unknown, see note* below) YAML = yaml
* class name not documented at time of this writing.
So for example, to specify a code block as C++, you would write:
Single line: <code class="language-cpp">...</code> Multi-line: <pre><code class="language-cpp">...</code></pre> Alternate: <pre class="language-cpp"><code>...</code></pre>
To disable Highlight.js syntax highlighting for any code block, add a class of nohighlight
, like so:
<code class="nohighlight">...</code>
Similarly, you can add a class of plaintext
to make arbitrary text look like code, but without highlighting:
<code class="plaintext">...</code>
I’m happy to add more languages, make a suggestion.
For plugin support, post a new topic in the Prismatic support forum at WordPress.org.
Thank you for using Prismatic :)