Installation and Compatibility

To utilize the Social Sharing plugin, ensure your Publii CMS is updated to version 0.43.1 or higher. This plugin is tailored for compatibility with the latest Publii theme versions, particularly those released around October/November 2023.

To add support for the Social Sharing plugin to your older or custom Publii themes, follow these steps:

1. Locate the Relevant File: Open your file explorer and navigate to the Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME directory, where YOUR_SITE is the name of your site, and YOUR_THEME is the folder for the theme you are currently using.
2. Edit the post.hbs File: Use your preferred code editor to open the post.hbs  file located in your theme's folder. 
3. Insert the Social Sharing Code:
   1. Find an appropriate place in the post.hbs file where you want the social sharing buttons to appear. It's typically placed near the bottom of the post template and looks like this: {{> share-buttons}}
   2. Replace the above code with the custom social sharing code snippet: {{{@customSocialSharing}}}.

   For instance, your code might look something like this:

   {{#if @config.post.displayShareButtons}}
     {{#checkIfAll @plugins.socialSharing @plugins.socialSharing.state}}
       <div class="post__share">
           {{{@customSocialSharing}}}
       </div>
     {{/checkIfAll}}          
   {{/if}}

General Settings

Button Display Modes

• Icon Only: Displays only the social platform icon, providing a clean and minimalistic look. Ideal for websites with a modern, uncluttered design.
• Text Only: Shows only the name of the social platform. This mode benefits users who prefer text labels for clarity and accessibility.
• Icon and Text: Combines both the icon and the text label, offering a comprehensive view that is both visually appealing and informative.

Layout Options

• Horizontal Layout: Aligns buttons in a linear row. Suitable for headers, footers, or any horizontal space in your website's layout.
• Vertical Layout: Stacks buttons in a column, ideal for sidebars or narrow vertical spaces like popups.

Button Types

• Link Buttons: Styled as text links with icons, these buttons offer a simple and minimalistic approach. The text and icon color can be adjusted to match your site's theme.
• Outlined Buttons: These buttons feature a distinct border, providing an elegant and defined appearance. The border color can be customized to align with your site's design or represent the social platform's color scheme.
• Solid Buttons: Solid buttons offer a bold, filled color, drawing more attention. They include a 'Luminance Adjust on Hover' feature, allowing the button to slightly change color when hovered over, enhancing the interactive experience.

Color Customization

Platform-Colored: These options dynamically adapt the color scheme of the buttons based on the selected social media platform, ensuring visual harmony and brand consistency. They allow you to configure colors for both the default and hover states, depending on your preferences and the design of your site.

Depending on the type of button you choose (link, outlined, or solid), you will have the flexibility to customize various elements of the buttons with color options specific to each platform:

Link Buttons:

• Text: Choose to colorize the text of the link buttons.
• Icon: Opt for coloring the icons within the link buttons.
• Both Icon and Text: Apply colorization to the text and icons within link buttons.

Outlined Buttons:

• Border: If you're using outlined buttons, you can select this option to colorize the border.
• Text and Icons: This option lets you colorize the text and icons for outlined buttons.
• Border, Text, and Icons: This comprehensive option allows you to colorize the border, text, and icons for outlined buttons.

Solid Buttons:

• Background: You can also colorize the solid buttons' backgrounds, providing further customization possibilities.

Platform-colored options simplify the process, ensuring your buttons seamlessly match the color schemes of social media platforms, resulting in a cohesive and visually appealing user experience tailored to your site's theme and the selected button type.

Social Platforms

In this section, you can select and configure various social media platforms for sharing content from your website. It allows for rearranging the order of social buttons using a drag-and-drop method and renaming the buttons. For example, you can rename a button from "Facebook" to "Share with Facebook" for more precise user guidance.

This section not only allows for the selection of social media sharing buttons but also provides several additional options that are essential for specific platforms.

• Facebook App ID: Enter your Facebook App ID here. This ID is essential for enabling features like sharing via Facebook Messenger.
• Twitter Handle: Define your Twitter account's handle. This handle is appended when sharing content via Twitter, for example, 'via @TwitterHandle'. If left blank, the author's Twitter handle is used.
• Clipboard Alert Text: Customize the alert text when a URL is copied to the clipboard. The default text is "URL copied to clipboard".
• Mastodon Domain Label: Customize the label text for the Mastodon domain input field. This label appears as a prompt when users are asked to enter their Mastodon domain.

Styling Options

• Text Color: Allows customization of the text color on buttons, ensuring alignment with your website's color scheme. 
• Text Color on Hover: Defines the text color when the mouse hovers over the button. 
• Icon Color: Customizes the color of icons within the button. This setting is available when specific button styles and platform color conditions are met.
• Icon Color on Hover: Changes the icon color on mouse hover, enhancing user interaction. 
• Border Text Color: Alters the text color for buttons with borders. This option comes into play based on the button style and specific platform-colored border conditions.
• Background Color: Sets the background color of buttons, allowing for a harmonious integration with the site's design. It is dependent on the button style and platform background color settings.
• Luminance Adjustment: Modifies the luminance of the social platform's background color on hover, offering a customizable visual effect. This feature allows for lightening or darkening the button color in the hover state, providing dynamic visual feedback to the users. 
• Border Width: Allows setting the border width for buttons, providing a way to adjust button aesthetics based on design requirements. 
• Button Hover Effect: Select the hover effect for buttons. Available options include: None, Translate Up, Scale, Rotate, Skew, Scale and Translate, Translate XY, Rotate and Scale, and Custom. This feature enhances the interactive experience by allowing diverse animations and transformations on hover.
• Button Padding: Adjusts the padding around buttons, ensuring comfortable spacing and alignment with the overall design. 
• Button Border Radius: Defines the border radius for buttons, allowing for rounded or sharp edges based on stylistic preferences. 
• Font Family: Choose the font family for button text, ensuring typographic consistency with your site's design. This option supports official Publii theme fonts and allows for custom font specifications. It's compatible with the theme's CSS font variables, making it easy to align with the overall design aesthetics of your website.
• Font Size: Adjusts the font size for button text, aligning it with your website's typography for a cohesive look.

Advanced Customization

• Container CSS Class: Define a custom CSS class for the container. The default value is "scl-container". This option allows for advanced styling and layout control.
• Button CSS Class: Set a specific CSS class for buttons. The default value is "scl-btn". Helpful in applying custom styles and behaviors to buttons.
• Theme's Popup Container CSS Class: Specify the CSS class name for the theme's popup container, with the default value being js-post__share-popup. Keep this default class unless you use a custom popup to display social media buttons with your class name. The default class name is integral for official Publii themes, where social media buttons are displayed in a popup activated by a "Share" button. Only change this class if you use your popup implementation with a different class name, as this is crucial for ensuring the plugin functions correctly in such customized setups.
• Social Sharing Popup: Toggle to enable or disable a popup window for social sharing buttons. This feature enhances user interaction by providing a dedicated sharing interface.
• Popup Width: Define the width of the popup in pixels. This setting is active only when the social sharing popup is enabled.
• Popup Height: Set the height of the popup in pixels. This configuration is applicable when the social sharing popup feature is active.

Optimized Performance: Intelligent Icon Mapping and Selective CSS Loading

By employing optimized SVG icons, the Social Sharing plugin guarantees a swift, visually appealing display with minimal impact on load times. A key feature is intelligent icon mapping, which dynamically generates a map of icons based on the specific social platforms chosen by the user. This approach ensures that only selected icons are loaded, avoiding the redundancy of unused graphics.

Furthermore, the plugin's smart CSS generation contributes significantly to performance efficiency. It customizes the CSS based on the button type, attaching only the needed CSS styles. For instance, in the case of a 'link' type button, which lacks borders or backgrounds, the plugin does not load styles related to these elements.

This meticulous attention to detail in code management means that the plugin enhances the user interface and maintains a lightweight presence on the host website, ensuring optimal page performance.

HTML Output and Accessibility

The plugin excels in performance and demonstrates a commitment to accessibility. This is evident in the dynamically generated HTML code it produces, which includes specific ARIA (Accessible Rich Internet Applications) attributes tailored to the type of buttons.

For example, depending on the chosen display option ('Icon only', 'Text only', or 'Both'), the plugin attaches the necessary ARIA attributes to enhance accessibility. This approach is particularly beneficial for screen readers and assistive technologies, ensuring that all users can interact with the social sharing buttons effectively regardless of their abilities.

Below is a sample of the HTML code generated by the plugin for three different platforms, showcasing how it adapts to various scenarios while prioritizing accessibility and performance.

<!-- Example of generated HTML for three platforms -->
<div class="scl-container">
    <!-- Diaspora Button -->
    <a href="https://share.diasporafoundation.org/..." class="scl-btn p-diaspora" aria-label="Diaspora">
        <svg width="24" height="24" aria-hidden="true" ...></svg>
        <span>Diaspora</span>
    </a>
    <!-- Digg Button -->
    <a href="https://digg.com/submit?url=..." class="scl-btn p-digg" aria-label="Digg">
        <svg width="40" height="24" aria-hidden="true" ...></svg>
        <span>Digg</span>
    </a>
    <!-- Email Button -->
    <a href="mailto:?subject=..." class="scl-btn p-email" aria-label="Email">
        <svg width="24" height="24" aria-hidden="true" ...></svg>
        <span>Email</span>
    </a>
</div>

Customization with CSS Variables

While the plugin offers extensive styling options through its user interface, it allows advanced users to directly manipulate styles using CSS variables. These variables are dynamically generated and can be adjusted to tailor the appearance of the sharing buttons to fit the specific needs of a website.

Below is a list of CSS variables available for customization, categorized by different button styles: 'Links', 'Outlined buttons', and 'Solid buttons'. Each category includes variables for colors, hover states, icon colors, borders, and more, allowing for detailed and precise styling.

/* Links */

  --scl-link-color: Color of the link text;
  --scl-link-color-hover: Hover color of the link text;
  --scl-link-icon-color: Color of the link icon;
  --scl-link-icon-color-hover: Hover color of the link icon;


/* Outlined buttons */

  --scl-outlined-color: Text color for outlined button;
  --scl-outlined-color-hover: Hover text color for outlined button;
  --scl-outlined-icon-color: Icon color for outlined button;
  --scl-outlined-icon-color-hover: Hover icon color for outlined button;
  --scl-outlined-border-color: Border color for outlined button;
  --scl-outlined-border-color-hover: Hover border color for outlined button;
  --scl-outlined-border-width: Border width for outlined button;
  --scl-btn-padding: Padding for button;


/* Solid buttons */

  --scl-btn-bg: Background color of the button;
  --scl-btn-bg-hover: Hover background color of the button;
  --scl-btn-txticon-color: Text and icon color for button with background;
  --scl-btn-txticon-color-hover: Hover text and icon color for button with background;
  --scl-btn-padding: Padding for button with background;
  --scl-hsla-luminance: Luminance adjustment for button with background;


/* General Variables */

  --scl-container-gap: Gap between container elements;
  --scl-container-direction: Layout direction of the container (row/column);
  --scl-btn-hover-effect: Hover effect for buttons;
  --scl-btn-gap: Gap between buttons;
  --scl-btn-transition: Transition effect for buttons;
  --scl-btn-border-radius: Border radius for buttons;
  --scl-btn-font-family: Font family for buttons;
  --scl-btn-font-size: Font size for buttons;
  --scl-icon-size: Size of the icon;

These variables provide a high degree of customization, empowering users to fine-tune the aesthetic aspects of the social sharing buttons to integrate with their website design seamlessly.

The Smart Replacer Plugin is a powerful tool for automating text and regular expression replacements throughout your Publii website. This guide offers a comprehensive walkthrough for enabling, configuring, and using the plugin to its full potential.

Enabling the Plugin

1. Open the Publii application and go to the Tools & Plugins section.
2. Find the Smart Replacer plugin from the list of installed plugins.
3. Activate it by toggling the switch button at the plugin tile's bottom-left corner.

Configuration Overview

Once the plugin is enabled, you'll find various configuration options to control how the text and regular expression replacements function. These settings are categorized under "General Settings," "Replacement Rules," "Regular Expressions Rules," and "Global Regular Expressions Rules," each serving a specific purpose in how the plugin behaves.

General Settings

Enable Global Configuration: Check this box if you want a single set of configurations to apply to all rules. If enabled, all rules will share these global settings. Disable this to configure each rule individually.

Application Scope

These options define where your rules will be applied. Each of these settings is accessible only when the Global Configuration is enabled.

• Apply Rules to Excerpt: Enables the application of the replacement rules to the excerpts of your posts.
• Apply Rules to Post Content: Ensures the replacement rules are applied to the body text of your posts.
• Apply Rules to Post Title: Activates the replacement rules for the titles of your posts.

Replacement Rules

This section is designed for creating rules specific to plain text replacements.

• Value to Replace: Specify the text fragment you aim to replace.
• Text to Use: Insert the text to replace the specified fragment.
• Use in Excerpt: If Global Configuration is disabled, check this box to apply this rule to post excerpts.
• Use in Post Text: If Global Configuration is disabled, check this box to apply this rule to the body text of posts.
• Use in Post Title: If Global Configuration is disabled, check this box to apply this rule to post titles.

Example: If you want to replace the term "CMS" with "Content Management System" throughout your posts, set Value to Replace: CMS and Text to Use: Content Management System. You can also create a shortcode, such as [banner], and replace it with an ads banner or any other text.

Regular Expressions Rules

This section allows you to create rules that utilize regular expressions for more complex replacements.

• Regular Expression: Input the regular expression pattern to be matched.
• Text to Use: Define the text that will replace the matched regular expression.
• Use in Excerpt: If Global Configuration is disabled, enable this rule for post excerpts.
• Use in Post Text: If Global Configuration is disabled, enable this rule for the text body of posts.
• Use in Post Title: If Global Configuration is disabled, enable this rule for post titles.

Example: To add a "noffolow" attribute and icon to any external URL address set: Regular Expression: /<a href="http:\/\/|https:\/\/(?!www\.yourdomain\.com)(.*?)">/g and Text to Use: <a href="http://$1" target="_blank" rel="noffolow"><i class="external-icon"></i>

Global Regular Expressions Rules

These are similar to the Regular Expressions Rules but apply globally across different elements and pages of the website.

• Regular Expression: Define the global regular expression pattern.
• Text to Use: Enter the global replacement text.
• Select Range for this Rule: Choose whether this global rule will apply to the <head>, <body>, or the entire <html> of the page.
• On Which Pages Use this Rule?: Decide whether this global rule should be applied on all pages or only selected ones. Further granularity is provided for specifying pages like homepage, posts, tags, or authors.

Example: To replace all instances of "http" with "https" in the entire HTML set: Regular Expression: /http:\/\//g and Text to Use: https://

Advanced Settings

The Advanced Settings section offers control over the execution priority of text and regular expression replacements in different contexts. This is particularly useful when multiple plugins affect the same content areas.

Setting Priorities

You can set priorities for each content area: post titles, post text, post excerpts, and the overall HTML output.

• Post Title Replacement Priority: This setting allows you to specify the execution order for title replacements when multiple plugins are active. A higher value means this plugin's operations will execute later.
• Post Content Replacement Priority: Define the priority for text replacements within the post content. Again, a higher value delays this plugin's operation.
• Post Excerpt Replacement Priority: Use this to control the priority for excerpt text replacements when other plugins can modify the excerpt. A higher value will postpone this plugin's changes.
• HTML Output Replacement Priority: This setting controls the priority for HTML output replacements. A higher value will postpone this plugin's changes if multiple plugins modify the HTML.

Note: The default value for all priority settings is 1. You can adjust these based on your requirements to avoid conflicts with other plugins.

While the Advanced Head Tag Manager plugin offers powerful customization options for your website's metatags, it requires a good understanding of SEO principles and web development. Incorrect usage can potentially negatively impact your site’s SEO performance. Ensure you are familiar with SEO best practices before making advanced changes.

Enabling the Plugin

1. Open the Publii application and navigate to the Tools & Plugins section.
2. Locate the Advanced Head Tag Manager plugin in the list of installed plugins.
3. Activate the plugin by clicking the switch button at the bottom-left corner of the plugin tile.

Advanced Head Tag Settings

This section provides a range of options to customize various aspects of how metatags are managed on your website. The settings are organized into different groups, such as "Global Changes," "Homepage," "Posts," and more, allowing you to tailor the plugin's behavior both globally and for specific types of pages.

Global Changes

Unless overridden by specific page settings, these settings apply globally across your entire website.

• Remove generator metatag: Enabling this option will remove the generator metatag that typically displays "Publii Open-Source CMS for Static Site." This is useful for obscuring your CMS, which can be a security measure.
• Remove charset metatag: This allows you to remove the charset metatag, which specifies the character encoding for the HTML document. If you remove this metatag, add your own appropriate charset declaration to avoid character encoding issues.
• Remove viewport metatag: Removes the viewport metatag, affecting how your site scales on mobile devices. Be cautious with this setting, as the absence of a viewport metatag can significantly impact your website's mobile-friendliness, which Google considers for ranking. Only remove this metatag if you intend to use a custom viewport metatag. Neglecting this can result in your website being treated as non-mobile by search engines, adversely affecting your site's SEO.
• Remove X-UA-Compatible metatag: This removes the metatag used for specifying document compatibility modes in IE.
• Metatags to Remove: You can specify additional metatags to be removed globally from your site. You'll have to determine the type (name, property, or http-equiv) and the value for each tag.
• <head> code to add: Add custom code snippets to all pages' head sections. For dynamic content, you can use insertions like {meta_title}, {meta_description_raw}, {meta_description_raw}, {meta_robots_raw} 
  
  Example: 

  <meta name="custom-meta" content="{meta_title}">

Homepage

These settings apply only to the homepage, overriding any global settings.

• Modify homepage metatags: Check this box to enable customization of homepage-specific metatags.
• Metatags to Remove: Add specific metatags to be removed from the homepage. Similar to the global settings, you'll need to specify the type and value.
• <head> code to add: Add custom code to the head section of the homepage. The same insertions available in global settings can be used here.
  
  Example: 

  <meta name="custom-meta" content="{meta_title_raw}">

Posts, Tags, Authors, Pagination, 404 Error Page, and Search Page

For each section corresponding to the type of page, you can enable or disable the modification of metatags specific to those pages. These settings will override global settings if enabled. Each section allows you to:

• Remove specific metatags
• Add custom code to the <head> section

Each page type, such as the homepage, has unique insertions that can be checked in the notes provided within the plugin or in the table below:

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.

Enabling the Plugin

To activate the Collapsible TOC plugin, navigate to the Tools & Plugins section of the Publii app, accessible via the left-hand menu. Here, you'll find a list of installed plugins. In this list, locate the Collapsible TOC tile and click on the switcher button in the bottom-left corner of the tile to activate the plugin.

Immediately upon activation, the plugin will modify any existing Tables of Contents on your site, adding collapsible functionality and a range of customizable features. However, the Collapsible TOC plugin also offers a number of settings that you can adjust to ensure it aligns with your requirements.

To access these settings, click on the Collapsible TOC tile again, but make sure to click anywhere except on the switcher button. This will open the settings screen where you can adjust various aspects of the plugin. Please note, this settings screen will not be accessible if the plugin is not enabled first.

Collapsible TOC Settings

When the Collapsible TOC plugin is activated, a settings screen becomes available. On this screen, you will find two main groups of settings that you can customize: "Options" and "Theme integration".

Options

The "Options" group provides control over the functionality and display of the collapsible Table of Contents. Here are the settings you can adjust within this group:

• Toggle view: Controls the initial visibility state of the Table of Contents. When this option is enabled, the Table of Contents will be collapsed by default, but may be expanded or collapsed by the user. If this option is not enabled the TOC will be expanded by default, but can still be collapsed by the user if needed.
• Toggle element: Select which element (the TOC header, the button, or both) will toggle the TOC subsection visibility when clicked.
• Show/Hide button text: Customize the text that will be displayed on the button when the TOC is hidden or shown.
• Automatic height: Enable this to adjust the TOC height dynamically based on the content; if not enabled, the height can be configured manually.
• Custom maximum height: Only visible if the Automatic Height option is disabled. Allows a custom value for the maximum height of the TOC to be entered using pixels (px) or root element (rem) e.g. "500px", "20rem".

Theme Integration

The "Theme Integration" group focuses on how the TOC integrates with your Publii's theme. Here are the settings available within this group:

• Header title: Customize the content of the TOC header; if left blank, the default content from the article in which the TOC appears will be used.
• Heading level: Change the heading level for the TOC header. Publii generates an H3 heading by default, but here you can change it to any heading level from H1 to H6 as needed.
• List Style: This option allows users to choose the numbering style for their Table of Contents. Select the appropriate option in the drop-down list to specify your preferred styling:
  • Decimal (1, 2, 3, 4, 5, ...):  decimal numbers.
  • Decimal Leading Zero (01, 02, 03, 04, 05, ...): decimal numbers with a leading zero for single-digit numbers.
  • Lower Roman (i, ii, iii, iv, v, ...): lowercase Roman numerals.
  • Upper Roman (I, II, III, IV, V, ...): uppercase Roman numerals.
  • Lower Alpha/Latin (a, b, c, d, e, ...): lowercase letters.
  • Upper Alpha/Latin (A, B, C, D, E, ...): uppercase letters.
  • Lower Greek (α, β, γ, δ, ε, ...): lowercase Greek letters.
  • None - no markers: this option will not apply any specific numbering or bullet style to the TOC entries.
• Scroll padding top: Adjust the space between the top of the page and the section heading of the article once the user has clicked on an item in the TOC and the page scrolls to it. This can be helpful to ensure titles and content are not hidden under a header or navigation bar at the top of the screen. 

  Tip: Instead of using specific values such as "2rem" or "2vh", you can utilize a CSS variable like var(--navbar-height) if it's defined in your theme. Using this variable can help ensure that the jumped-to section will not be hidden underneath the top menu bar (header).

Remember to click on the "Save" button at the bottom-right of the screen after making any changes to these settings.

What code generates the Collapsible TOC?

After the plugin is activated, the structure of the HTML TOC generated by Publii is transformed to be more semantic and accessible. The standard unordered list (ul) is replaced with an ordered list (ol), denoting the hierarchy of the content. Furthermore, the nav element is used instead of the div to wrap the TOC, which improves the screen reader experience by indicating the navigational role of this section. The ARIA attributes aria-expanded and aria-hidden are used to improve accessibility by providing additional information about the state of the TOC.

Before enabling the plugin, your Table of Contents look like this:

<div class="post__toc">
  <h3>Table of Contents</h3>
  <ul>
    <li><a href="#mcetoc_1h376r6091m">Introduction</a>
      <ul>
        <li><a href="#mcetoc_1h376r6091n">Chapter 1</a>
          <ul>
            <li><a href="#mcetoc_1h376r6091o">Section 1.1</a></li>
            <li><a href="#mcetoc_1h376r6091p">Section 1.2</a></li>
          </ul>
        </li>
        <li><a href="#mcetoc_1h376r6091q">Chapter 2</a></li>
      </ul>
    </li>
    <li><a href="#mcetoc_1h376r6091v">Summary</a></li>
  </ul>
</div>

After enabling the plugin:

<nav class="post__toc" aria-expanded="false">
  <h3 id="sublist-0" tabindex="0">
    <span>Table of Contents</span>
    <button class="post__toc-toogle">Show</button>
  </h3>
  <ol aria-hidden="true">
    <li><a href="#mcetoc_1h376r6091m">Introduction</a>
      <ol>
        <li><a href="#mcetoc_1h376r6091n">Chapter 1</a>
          <ol>
            <li><a href="#mcetoc_1h376r6091o">Section 1.1</a></li>
            <li><a href="#mcetoc_1h376r6091p">Section 1.2</a></li>
          </ol>
        </li>
        <li><a href="#mcetoc_1h376r6091q">Chapter 2</a></li>
      </ol>
    </li>
    <li><a href="#mcetoc_1h376r6091v">Summary</a></li>
  </ol>
</nav>

Remember, by adjusting the settings in the plugin, you can customize how this structure behaves and looks in your Publii site.

Customizing the Table of Contents (TOC) Appearance

While your Publii site's theme primarily dictates the appearance of the Table of Contents (TOC), the 'Collapsible TOC' plugin provides additional control over the styling of the TOC toggle button (Hide/Show). This plugin gives you the ability to enhance the aesthetics of this feature.

These changes may be made in the Custom CSS tool, located in the Tools & Plugins section of the Publii main menu.

Available CSS variables

The 'Collapsible TOC' plugin for Publii offers support for CSS variables provided by your site's Publii theme. This compatibility helps ensure the styling of your table of contents (TOC) and the TOC toggle button remains consistent with the rest of your site's aesthetics.

However, there may be situations where you want the TOC to have a distinct appearance that doesn't mirror the rest of your site. In such cases, you can override the theme's CSS variables using the dedicated plugin classes. These dedicated classes allow you to customize the TOC independently of the theme's variables.

Here is a list of CSS variables you can use to adjust the appearance of the TOC. You can copy the entire block of code to your Custom CSS tool and modify it as per your needs. You also have the option to change only specific variables from the list.

:root {    
    --toc-link-color: red;
    --toc-link-color-hover: black;
    --toc-number-color: black;
    --toc-toggle-color: black;
    --toc-toggle-link-color: red; 
    --toc-toggle-link-color-hover: red;  
  } 

Here's what each of these variables does:

• --toc-link-color: This variable changes the color of the TOC links.
• --toc-link-color-hover: This variable changes the color of the TOC links when they are hovered over, active, or in focus.
• --toc-number-color: This variable modifies the color of the numbers or bullets in the TOC.
• --toc-toggle-color: This variable changes the color of the TOC toggle button, specifically the square brackets.
• --toc-toggle-link-color: This variable changes the color of the TOC toggle button link.
• --toc-toggle-link-color-hover: This variable changes the color of the TOC toggle button link when it is hovered over.

Customizable CSS Classes for TOC Elements

In addition to CSS variables, the 'Collapsible TOC' plugin also provides specific CSS classes that target various elements of the Table of Contents. Using these classes, you can precisely adjust the appearance of individual components of the TOC to meet your site's styling requirements.

Here's a rundown of the classes you can use to style the TOC:

/* Main container for the Table of Contents */
.post__toc {}

/* Table of Contents when it's expanded */
.post__toc[aria-expanded="true"] {}

/* Table of Contents when it's collapsed */
.post__toc[aria-expanded="false"] {}

/* The hide/show for showing and hiding the Table of Contents */
.post__toc-toggle {}
    
/* Styling for the hide/show button when hovered, active or focused */
.post__toc-toggle:hover, 
.post__toc-toggle:active, 
.post__toc-toggle:focus {}

/* Styling for the square brackets elements before and after the hide/show button */
.post__toc-toggle::before, 
.post__toc-toggle::after {}
    
/* Styling for the table of contents header, which contains the text and hide/show button. 
   The tag (H3 here) could vary based on the option chosen in the plugin settings, and can range from H1 to H6. */
.post__toc h3 {}

/* The ordered list (ol) directly under the main container */
.post__toc > ol {}

/* The ordered list when it's visible */
.post__toc > ol[aria-hidden="false"] {}

/* The ordered list when it's hidden */
.post__toc > ol[aria-hidden="true"] {}

/* All ordered lists (ol) in the Table of Contents */
.post__toc ol {}

/* List items (li) in the ordered list (ol) */
.post__toc ol li {}
    
/* Styling for the anchor links (a) in the table of contents */
.post__toc a {}

/* Styling for the numbers appearing before the anchor links */
.post__toc a::before {}

With this plugin, integrating Matomo Analytics into your Publii site is a cinch; no need to manually add code to your site, and GDPR-cookie banner compatibility allows visitors to easily provide consent to tracking cookies if required.

Setting Up Matomo

Before using the plugin, an account must be created with Matomo in order to receive the credentials required to activate the plugin, and to configure the analytical options to suit your site's needs. To create an account, follow these steps:

1. Open your browser to Matamo's homepage and click on the Try Free Cloud Trial button in the header to be taken to the account creation screen.
2. On the account creation screen, you will need to enter your email address and provide the URL for the website you wish to track. Once done, make sure to click the checkbox to accept the terms and conditions, then click the Start improving your websites now button to continue.
3. An email will be sent by Matomo with a Matomo analytics domain for your site, plus a username and password that you will need to use to login to your account. Once you have received this email, you can proceed to the next step.
4. On the next screen you will need to complete the account creation process; enter your Matomo Analytics domain as provided in the account creation email from the previous step, then click the Log in button. Keep a note of this domain as you will need to enter it into the Publii plugin settings later.
5. A new login screen will open; here you will need to enter the Username and Password provided by Matomo in their confirmation email, the click the Log in button.
6. Once logged-in, the first screen you will see will be to integrate the tracking code into your site. We don't need this information since the plugin will take care of it for us. Instead, click on the Integrations tab under the Choose your preferred way of setting up title to open the integration information section.
7. From this section, make a note of the Matomo URL and site ID; we will need to enter this information into the plugin in Publii to allow your site to start tracking analytics. Your account is now setup and we can move to enabling and setting up the plugin.

Installing the Plugin

The Matomo Analytics plugin is not included in the standard Publii installation; in order to get access to the plugin, it will first need to be downloaded via the Publii Plugin Marketplace, then installed through the Publii app. To do so, follow these steps:

1. Open Publii’s App Menu by clicking on the three dots icon in the top-right of the app UI; this icon is always visible except when creating or editing a new post, tag or menu.
2. In the menu that appears, click on Plugins. This will take you to the Plugins page where you can see any plugins that you have installed.
3. Click on the Get More Plugins box to open your browser at the Publii Plugins Marketplace, which displays all the currently available plugins.
4. Click on the Matomo Analytics plugin box to open the description page. From here, you can click the Download button under the description to download the zipped install package.
5. Once the download has finished, in the Plugins screen of the Publii app, click on the Install Plugin button at the top of the page. This will open your file explorer; browse to the folder where you downloaded the plugin file, and select it. Publii will automatically install the plugin and add it to the list of available plugins in both the Plugins and Tools & Plugins pages in Publii.

Activating the Plugin

The plugin can be enabled by clicking the switcher button in the Matomo Analytics box of the Tools & Plugins section of the Publii app. If the switcher changes from grey to blue. then the plugin is enabled. You will need to enter both your Matomo URL and Site ID into the plugin options before the plugin can function properly; to do so, open the Plugin Options screen by clicking anywhere in the Matomo Analytics box anywhere except on the switcher button; this will open the Plugin options screen, where you can add the necessary information. For the other options contained in this section, more details may be found in the next section of this guide.

Matomo Analytics Plugin Options

This plugin has two required settings, Matomo URL and Site ID, but it also includes options for integrating Matomo consent requests into the cookie banner. The options in the plugin are as follows:

Configuration

• Matomo URL - Enter the Matomo URL as provided in the confirmation email sent by Matomo when creating an account, and also on the Integrations tab of the Matomo settings after logging-in on the Matomo website.
• Site ID - Enter the Site ID as provided via the Integrations tab of the Matomo settings after logging-in on the Matomo website.
• Output Code in Preview Mode - If enabled, the code used to provide tracking data to Matomo Analytics will be included when clicking the Preview your changes button in Publii. This is useful when debugging to ensure the code is generated correctly, but generally should be disabled to prevent incorrect data being included in your analytics.

Cookie Banner Integration

• Cookie Banner Integration - Enabling this option will add an option to the built-in Publii cookie banner for users to consent to cookies from Matomo. Depending on your analytics settings in Matomo, cookies may or may not be required.
• Cookie Group ID - This option only becomes available when the Cookie Banner Integration option is enabled. Here, you can specify the cookie group that the Matomo cookies should be added to. Make sure to add the group name to the GDPR section of the site settings. You can find instructions on how to do this in the GDPR section of this documentation.