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 visually appealingly, this plugin guarantees that developers and readers alike have an optimal experience. Below is a comprehensive guide to enabling and configuring 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 can access 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 several ways to customize how your code is displayed. The settings available within this group can help make your code more readable and accessible to others:

• Show line numbers: Enable this feature to number each line of your code. This offers readers a more accessible reference point.
• ‘Copy to Clipboard’ button: Allows users to copy code snippets with just one click.
• Inline color preview: Handy 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 how 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 at the bottom-right of the settings screen to ensure your modifications take effect.

Using the Syntax Highlighter plugin

The Syntax Highlighter plugin in Publii offers versatile options for integrating code into your content, whether using the Block Editor or the enhanced WYSIWYG editor.

Block Editor Integration

With the Block Editor, embedding code is straightforward. When you write your code within the CODE block, it is automatically formatted and highlighted according to the language specified. This method ensures that the code is displayed correctly with minimal manual intervention.

WYSIWYG Editor Integration

The WYSIWYG editor now includes a dedicated feature for embedding code. This can be accessed via a button in the editor's menu. Upon clicking this button, a popup appears, allowing you to select the programming language from a dropdown menu and enter your code in a text area. This method automatically wraps your code in the necessary markup for syntax highlighting.

Manual Code Embedding

Manual code embedding is still available for users who prefer a more hands-on approach or are not using the Block Editor. Enter the following markup in the WYSIWYG editor and add the appropriate class for your code's language:

<pre class="language-sufix"><code> ...your_code_here... </code></pre>

Note: The class "language-sufix" represents the language you've written your code. The suffix, 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 (exactly the same as the Block Editor): 

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. You can easily adapt and override these themes by copying the CSS blocks (variables) 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.