Prismatic – Beautiful Syntax Highlight for Code Snippets

Εγκατάσταση

Installing Prismatic

1. Make a backup of your database
2. Upload the plugin to your blog and activate
3. Visit the plugin settings to configure options

More info on installing WP plugins

Quick Start Guide

Here is a quick guide to get started with Prismatic:

1. Activate the plugin and visit the Prismatic settings page
2. Choose Prism.js or Highlight.js for syntax highlighting
3. Optionally visit the Prism.js or Highlight.js tab to customize options

You are now ready to go. To add a code snippet to any WP Post or Page:

• If using Gutenberg Block Editor, click on the Prismatic block
• If using Classic Editor, click on the Prismatic TinyMCE button

To get a better idea, view the screenshots on the Prismatic homepage.

The Prismatic block or button makes it easy to add your code snippet and choose a language. The plugin automatically will output the correct markup to display your code with syntax highlighting. No code editing required! Note: Advanced usage information provided further down on this page.

Like the plugin?

If you like Prismatic, please take a moment to give a 5-star rating. It helps to keep development and support going strong. Thank you!

Uninstalling

Prismatic cleans up after itself. All plugin settings will be removed from your database when the plugin is uninstalled via the Plugins screen. NOTE that uninstalling the plugin will NOT touch any of your post content. Only the plugin options are removed when the plugin is uninstalled via the Plugins screen.

Restore Default Options

To restore default plugin options, either uninstall/reinstall the plugin or visit the Prismatic General Settings > Restore default plugin options.

Usage: Syntax Highlighting

The Prismatic plugin follows the same conventions used by Prism.js and Highlight.js. Here are the basic steps:

1. Visit the Prismatic General Settings and choose your library
2. Visit the settings tab for your chosen library
3. Choose a theme and configure your options

Once the settings are configured, you can enable syntax highlighting for any code snippet by doing one of the following:

• Wrap multi-line code with pre & code tags: <pre><code>…</code></pre>
• Wrap single-line code with code tags: <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 class="optional">
    <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>

Note: in the previous example, ignore the class="optional" added to the code tag; it is used to prevent markdown from mangling the code example on this web page.

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.

Pro Tip: Language class names work when added to the <pre> tag for both Prism.js and Highlight.js.

Usage: Code escaping

Just like Prism.js and Highlight.js, the Prismatic plugin follows HTML coding standards. To enable code escaping:

1. Visit the Prismatic General Settings and choose your library
2. Enable “Code Escaping” via the settings tab of your chosen library
3. Do one of the following:
   • Wrap multi-line code with pre & code tags: <pre><code>…</code></pre>
   • Wrap single-line code with code tags: <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):

• Frontend only – code snippets are escaped at runtime (no changes made to content in the database)
• Admin Area only – code snippets are escaped when viewed via the Admin Area (changes will be saved to database if the “Update” or “Publish” button is clicked)
• Frontend & Admin Area – both of the previous are applied
• None – all code escaping is disabled

Note that 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:

&                     replaced with &
<                     replaced with &lt;
>                     replaced with &gt;
"                     replaced with &quot;
'                     replaced with '
\r                    removed
trailing whitespace   removed

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.

Usage: Gutenberg Block Editor

To highlight a code block using Gutenberg:

1. Select the Prismatic block
2. Select a code language (via sidebar options)
3. Add your code and done.

Usage: Classic TinyMCE Editor

To highlight code using the TinyMCE/Visual/Rich-Text Editor:

1. Click the Prismatic button (looks like <>)
2. Choose a code language
3. Add your code and click “OK” button

There also is a Prismatic Quicktag button (“pre”) for those using the Plain-Text editor.

Usage: Prism.js Plugins

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.

• Line Highlight – Requires adding data-line attribute to the pre element
• Line Numbers – Requires adding line-numbers class to the pre element
• Show Language – No additional steps required
• Copy to Clipboard – No additional steps required
• Command Line – Requires adding command-line class to the pre element

Note for adding extra classes: If using the Gutenberg Block Editor, you can add extra classes to your code blocks like so:

1. On the “Edit Post” screen, add the Prismatic block
2. Click the 3-dot (options) button for the block
3. Click “Show more settings”

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

About Prism.js

Prism.js version used in Prismatic plugin: 1.29.0

Prism.js resources

• Homepage
• GitHub
• Changelog

License & Info

/*
    Prism: Lightweight, robust, elegant syntax highlighting
    MIT license https://www.opensource.org/licenses/mit-license.php/
    @author Lea Verou https://lea.verou.me
*/

Supported Languages

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

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 class="optional">...</code></pre>

Note: in the previous example, ignore the class="optional" added to the code tag (for the “Alternate” syntax); it is used to prevent markdown from mangling the code example on this web page.

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>

I’m glad to add more languages, make a suggestion

About Highlight.js

Highlight.js version used in Prismatic plugin: 11.6.0

Highlight.js resources

• Homepage
• GitHub
• Changelog

License & Info

/*
    Syntax highlighting with language autodetection.
    Copyright (c) 2006, Ivan Sagalaev https://highlightjs.org/
    All rights reserved. BSD3 License @ https://git.io/hljslicense
*/

Supported Languages

Language       Class

Apache         = 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
Groovy         = groovy
HTML/XML/Etc.  = xml, html, xhtml, rss, atom, xjb, xsd, xsl, plist
HTTP           = http, https
Ini/TOML       = ini, toml
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
Perl           = perl, pl, pm
Plaintext      = plaintext, txt, text
PowerShell     = powershell, ps
Properties     = properties
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
TypeScript     = typescript, ts
VB.Net         = vbnet, vb
Verilog        = verilog, v
VHDL           = vhdl
Vim Script     = vim
YAML           = yaml

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 class="optional">...</code></pre>

Note: in the previous example, ignore the class="optional" added to the code tag (for the “Alternate” syntax); it is used to prevent markdown from mangling the code example on this web page.

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 glad to add more languages, make a suggestion