Smart Replacer Plugin

Introduction

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.

How the Plugin Works

The plugin works during page rendering, altering the output without modifying the raw content. This ensures that the original content remains unchanged while the displayed content is adjusted based on user-defined rules. The plugin searches for specified expressions and replaces them according to user settings, either within specific posts and pages or across the entire site globally.

Enabling the Plugin

Open the Publii application and go to the Tools & Plugins section.
Find the Smart Replacer plugin from the list of installed plugins.
Toggle 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.