Syntax Highlighter Plugin
The Syntax Highlighter plugin, with Prism.js integration, is a versatile addition to your website, ensuring your code snippets stand out and are easily readable. By presenting code in a visually appealing manner, this plugin guarantees that developers and readers alike have an optimal experience. Below is a comprehensive guide to enable and configure the Syntax Highlighter plugin for maximum utility.
Enabling the Plugin
- Open the Publii app and go to the Tools & Plugins section.
- Find the Syntax Highlighter plugin on the list of installed plugins.
- Click the switch button in the bottom-left corner of the plugin tile to activate it.
Syntax Highlighter Settings
Once the Syntax Highlighter plugin is enabled, you will have access to its settings screen. Here, the settings are conveniently divided into three categories: "Theme Configuration", "Display Options", and "Advanced Options".
Theme Configuration
The "Theme Configuration" group allows you to modify the appearance of your highlighted code. Here are the settings you can adjust within this group:
- Themes: Select from six distinctive color themes to modify the appearance of your highlighted code. Available options include: Beige, Black, Brown, Gray, Violet and White.
Display Options
The "Display Options" section provides a number of ways to customize the way your code is displayed. The settings available within this group can be helpful for making your code more readable and accessible to others:
- Show line numbers: Enable this feature to number each line of your code. This offers readers an easier reference point.
- ‘Copy to Clipboard’ button: Allow users to swiftly copy code snippets with just one click.
- Inline color preview: Particularly useful for style sheets, this feature lets readers visualize color codes through an inline preview.
- Auto linking: Turn URLs and emails within your code into clickable links.
- Show hidden characters: This feature uncovers hidden characters like tabs and line breaks. It's especially useful for those aiming for a deeper grasp of underlying code structures.
Advanced Options
The "Advanced Options" section allows you to customize the way the plugin scripts load. Here are the settings available within this group:
- Load on: Decide where you want the syntax highlighter scripts to load:
- Only on post pages
- On all pages (excluding ‘404’ and ‘search’ pages)
Remember, after making your desired changes, it's crucial to click on the "Save" button, located at the bottom-right of the settings screen, to ensure your modifications take effect.
Using the Syntax Highlighter plugin
The Syntax Highlighter plugin integrates most seamlessly with the Block Editor in Publii. This is because when a user writes their code within the CODE block, it's immediately prepared in the appropriate manner, as elaborated below.
If you're not using the Block Editor, then you need to manually enter the following markup in the WYSIWYG editor and add the appropriate class.
<pre class="language-sufix"><code> ...your_code_here... </code></pre>
Note: The class "language-sufix" represents the language in which you've written your code. The suffix, which is the abbreviation of the language in the table above, should be added to the end of the class. For example, the class for HTML code would be "language-html".
This plugin supports the following languages (exact same as the Block Editor):
Language | Suffix |
---|---|
Apache Configuration | apacheconf |
Bash | bash |
BASIC | basic |
Batch | batch |
BBcode | bbcode |
C | c |
C-like | clike |
C++ | cpp |
ColdFusion Script | cfscript |
CSS | css |
Dart | dart |
Docker | docker |
Elm | elm |
Git | git |
GLSL | glsl |
Go | go |
GraphQL | graphql |
HAML | haml |
Handlebars | handlebars |
Haskell | haskell |
HTML | html |
HTTP | http |
INI | ini |
Java | java |
JavaScript | javascript |
JavaScript Extras | js-extras |
JSONP | jsonp |
JSX | jsx |
JSON | json |
Kotlin | kotlin |
LaTeX | latex |
Less | less |
Lisp | lisp |
Lua | lua |
Makefile | makefile |
Markdown | markdown |
Markup | markup |
Markup Templating | markup-templating |
MATLAB | matlab |
NASM | nasm |
Nginx | nginx |
Objective-C | objective-c |
Pascal | pascal |
Perl | perl |
PHP | php |
PowerShell | powershell |
Pug | pug |
Python | python |
R | r |
Regular Expressions | regex |
RSS | rss |
Ruby | ruby |
SASS | sass |
SCSS | scss |
Scala | scala |
Scheme | scheme |
SQL | sql |
Swift | swift |
Twig | twig |
TypeScript | typescript |
VB.NET | vbnet |
Visual Basic | visual-basic |
YAML | yaml |
Customizing the Syntax Highlighter Appearance
The Syntax Highlighter plugin allows you to customize the appearance of code blocks using CSS variables. This gives you a great deal of control over the look and feel of your code, and allows you to create a consistent style across your entire website.
The plugin offers six pre-defined themes for syntax highlighting. If you wish, you can easily adapt and override these themes by copying the CSS blocks (variables) provided below into the Custom CSS tool.
/* Beige Theme */
:root {
--prism-text: #323C53;
--prism-bg: #F5F2F0;
--prism-light-shadow: white;
--prism-selection: #B3D4FC;
--prism-comment: slategray;
--prism-punctuation: #999;
--prism-namespace-opacity: 0.7;
--prism-property: #905;
--prism-string: #690;
--prism-operator: #9A6E3A;
--prism-operator-bg: rgba(255, 255, 255, 0.5);
--prism-atrule: #07A;
--prism-function: #DD4A68;
--prism-regex: #E90;
--prism-border: rgba(112, 128, 144, 0.7);
--prism-space: #808080;
--prism-url: #CF222E;
}
/* Black Theme */
:root {
--prism-text: #F6F6F9;
--prism-bg: #1E2128;
--prism-light-shadow: rgba(0, 0, 0, 0.3);
--prism-selection: #C1DEF1;
--prism-comment: rgba(255, 255, 255, .5);
--prism-punctuation: #B3B9C5;
--prism-boolean: #E1A6F2;
--prism-namespace-opacity: .7;
--prism-property: #6AB0F3;
--prism-string: #FFD479;
--prism-operator: #AC8D58;
--prism-atrule: #92D192;
--prism-keyword: #FFEEAD;
--prism-regex: #FD971F;
--prism-border: #4C4C4C;
--prism-space: #808080;
--prism-url: #ED8EB2;
}
/* Brown Theme */
:root {
--prism-text: #D7CFD6;
--prism-bg: #322931;
--prism-light-shadow: rgba(0, 0, 0, 0.3);
--prism-selection: #C1DEF1;
--prism-comment: #797379;
--prism-punctuation: #B9B5B8;
--prism-boolean: #FD8B19;
--prism-namespace-opacity: .7;
--prism-property: #FDCC59;
--prism-string: #149B93;
--prism-operator: #FD8B19;
--prism-atrule: #149B93;
--prism-keyword: #8FC13E;
--prism-regex: #149B93;
--prism-border: #6F5B6D;
--prism-space: #876F84;
--prism-url: #FD8A7D;
}
/* Gray Theme */
:root {
--prism-text: #323C53;
--prism-bg: #F6F6F6;
--prism-text-shadow: 0 1px white;
--prism-selection: #B3D4FC;
--prism-comment: #666F78;
--prism-punctuation: #999;
--prism-namespace-opacity: .7;
--prism-property: #C0341D;
--prism-selector: #2D61C9;
--prism-operator: #9A6E3A;
--prism-operator-bg: rgba(255, 255, 255, 0.5);
--prism-atrule: #07A;
--prism-function: #E09142;
--prism-regex: #E90;
--prism-border: rgba(112, 128, 144, 0.7);
--prism-space: #808080;
--prism-url: #C0341D;
}
/* Violet Theme */
:root {
--prism-text: #AFA0FE;
--prism-bg: #2A2734;
--prism-light-shadow: #4285F4;
--prism-selection: #4285F4;
--prism-comment: #959DAD;
--prism-punctuation: #959DAD;
--prism-namespace-opacity: .7;
--prism-property: #9EBEFF;
--prism-function: #9EBEFF;
--prism-string: #FC9;
--prism-operator: #DFEAFF;
--prism-atrule: #EBF2FF;
--prism-border: #3E4552;
--prism-space: #808080;
--prism-url: #FC98E9;
}
/* White Theme */
:root {
--prism-text: #24292F;
--prism-bg: white;
--prism-light-shadow: white;
--prism-selection: #9FC6E9;
--prism-comment: #6E7781;
--prism-punctuation: #24292F;
--prism-namespace-opacity: .7;
--prism-property: #0550AE;
--prism-string: #0A3069;
--prism-operator: #0550AE;
--prism-atrule: #CF222E;
--prism-function: #8250DF;
--prism-regex: #0A3069;
--prism-border: #D1D4D8;
--prism-space: #808080;
--prism-url: #CF222E;
}
Choosing Different Themes for Light and Dark Modes
If you'd like to use a different theme for dark mode (e.g., the black theme) while maintaining a different theme in light mode, you can achieve this using the prefers-color-scheme
media query. Here's how you can apply the black theme for dark mode:
@media (prefers-color-scheme: dark) {
/* Black Theme */
:root {
--prism-text: #F6F6F9;
--prism-bg: #1E2128;
... [rest of the variables]
}
}
By copying the above code into your Custom CSS tool on your website, the black theme will automatically be applied in dark mode, while your previously selected theme will remain in light mode.