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

1. Open the Publii app and go to the Tools & Plugins section.
2. Find the Syntax Highlighter plugin on the list of installed plugins.
3. 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.