Text Replacement Rules Reference

Text replacement rules define patterns and substitutions that are applied to your content. This page documents the structure of a rule and valid field values.

What Are Text Replacements?

Text replacements let you automate find-and-replace operations on your copied content. Rules are applied in two phases:

Pre-replacements: Applied to the HTML before it’s converted to Markdown. Use for cleaning HTML.
Post-replacements: Applied to the Markdown after conversion. Use for cleaning Markdown syntax.

For practical examples and workflow tips, see the Text Replacements Guide.

Rule Fields

Each text replacement rule is a JSON object with the following fields:

Field	Type	Required	Description
`id`	`string`	Yes	Unique identifier (UUID v4 format). Generated automatically.
`enabled`	`boolean`	Yes	Whether this rule is active.
`scope`	`string`	Yes	Where the rule applies. See Scope Values.
`useRegex`	`boolean`	Yes	Whether `pattern` is a regular expression.
`pattern`	`string`	Yes	The text or regex pattern to find.
`replacement`	`string`	Yes	The text to replace matches with.

Detailed Field Documentation

id

Type: string

Internal identifier for the rule. Used by Copymarky to track rule identity across edits and re-orders. Automatically generated as a UUID v4 (e.g., "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p").

Note: Users do not edit this field directly; it’s generated when creating a new rule.

enabled

Type: boolean

Whether this rule is active and will be applied to your content.

true: Rule is active and applied
false: Rule is disabled but kept in your settings (useful for temporary toggles)

Example:

{ "id": "...", "enabled": true, "scope": "all", ... }

scope

Type: "all" | "selection" | "page" | "link"

Specifies the context in which the rule applies. This allows you to use different rules for different content types.

Valid values:

"all": Applied to all copied content, regardless of context.
- Example: Removing ad placeholders that appear everywhere.
"selection": Applied only when copying selected text.
- Example: Normalizing formatting within highlighted snippets.
"page": Applied only when copying an entire page.
- Example: Removing page-wide navigation or footer content.
"link": Applied when copying a link (e.g., from a hyperlink context).
- Example: Stripping UTM parameters from URLs.

Example:

{
  "id": "remove-ads-abc123",
  "enabled": true,
  "scope": "all",
  "useRegex": false,
  "pattern": "[Advertisement]",
  "replacement": ""
}

useRegex

Type: boolean

Determines whether the pattern field is interpreted as a regular expression or literal text.

true: pattern is a regex; replacement supports backreferences ($1, $2, etc.)
false: pattern is matched literally; replacement is literal text

Regex conventions: JavaScript regex syntax (ECMA-262 standard).

Example (literal):

{
  "id": "remove-footer",
  "enabled": true,
  "scope": "all",
  "useRegex": false,
  "pattern": "© 2024 Example Inc.",
  "replacement": ""
}

Example (regex):

{
  "id": "normalize-dates",
  "enabled": true,
  "scope": "all",
  "useRegex": true,
  "pattern": "(\\d{1,2})/(\\d{1,2})/(\\d{4})",
  "replacement": "$3-$1-$2"
}

pattern

Type: string

The text or regex pattern to find in the content.

If useRegex is false (literal matching):

Treated as exact text to match
Special regex characters are not interpreted
Example: "[Advertisement]" matches the literal string [Advertisement]

If useRegex is true (regex matching):

Treated as a JavaScript regular expression
Supports regex syntax: ., *, +, ?, [...], (...), |, ^, $, etc.
Use escape sequences: \\ for backslash, \\d for digits, \\s for whitespace, \\w for word chars
Example: "^### (.+)$" matches any line starting with ###

Validation: Required field, cannot be empty.

Testing: Test your regex on regex101.com with the JavaScript flavor selected.

replacement

Type: string

The text to replace matches with.

If useRegex is false (literal):

Treated as literal replacement text
No special interpretation
Example: Replace "hello" with "goodbye" → all instances of “hello” become “goodbye”

If useRegex is true (regex):

Can include backreferences to captured groups in the pattern
Use $1, $2, $3, etc. to refer to captured groups
Use $& to refer to the entire match
Example: Pattern "(\w+) (\w+)" with replacement "$2 $1" swaps two words

Examples:

Literal replacement:

{
  "pattern": "TODO",
  "replacement": "[DONE]",
  "useRegex": false
}

Regex with backreferences:

{
  "pattern": "\\[(\\w+)\\]",
  "replacement": "<em>$1</em>",
  "useRegex": true
}

Validation: Required field. Can be empty (for deletions).

Example Rules

Example 1: Remove Ads (Literal)

Remove a common ad placeholder from all content.

{
  "id": "remove-ads-xyz789",
  "enabled": true,
  "scope": "all",
  "useRegex": false,
  "pattern": "[Advertisement]",
  "replacement": ""
}

What it does: Finds the exact string [Advertisement] and deletes it.

Example 2: Normalize Headings (Regex)

Convert level-3 headings to level-2 in the Markdown output.

{
  "id": "normalize-h3-to-h2-abc123",
  "enabled": true,
  "scope": "all",
  "useRegex": true,
  "pattern": "^### (.+)$",
  "replacement": "## $1"
}

What it does:

Finds lines starting with ### (level-3 heading)
Captures the heading text in group 1: (.+)
Replaces with ## (level-2) + the captured text

Example transformation:

### Getting Started
→
## Getting Started

Example 3: Remove URL Parameters (Regex)

Strip UTM tracking parameters from links.

{
  "id": "strip-utm-params-def456",
  "enabled": true,
  "scope": "all",
  "useRegex": true,
  "pattern": "\\?utm_[^&]*&?",
  "replacement": "?"
}

What it does:

Finds ?utm_ followed by any characters until & (or end)
Replaces with ? to preserve the remaining query string

Example transformation:

https://example.com/page?utm_source=twitter&foo=bar
→
https://example.com/page?foo=bar

Example 4: Convert Markdown Links to HTML (Regex)

Convert Markdown link syntax to HTML.

{
  "id": "md-to-html-links-ghi789",
  "enabled": true,
  "scope": "post",
  "useRegex": true,
  "pattern": "\\[([^\\]]+)\\]\\(([^)]+)\\)",
  "replacement": "<a href=\"$2\">$1</a>"
}

What it does:

Finds Markdown links: [text](url)
Group 1: link text
Group 2: link URL
Replaces with HTML: <a href="url">text</a>

Example transformation:

[Visit Example](https://example.com)
→
<a href="https://example.com">Visit Example</a>

Full Settings Example

Here’s how text replacement rules appear in an exported settings.json file:

{
  "headingStyle": "atx",
  "bulletListMarker": "-",
  "codeBlockStyle": "fenced",
  "linkStyle": "inlined",
  "imageHandling": "keep",
  "includePageTitle": true,
  "includeSourceUrl": true,
  "textReplacements": {
    "pre": {
      "enabled": true,
      "rules": [
        {
          "id": "remove-ads-xyz789",
          "enabled": true,
          "scope": "all",
          "useRegex": false,
          "pattern": "[Advertisement]",
          "replacement": ""
        },
        {
          "id": "clean-html-whitespace-abc123",
          "enabled": false,
          "scope": "all",
          "useRegex": true,
          "pattern": "\\s+",
          "replacement": " "
        }
      ]
    },
    "post": {
      "enabled": true,
      "rules": [
        {
          "id": "normalize-h3-to-h2-def456",
          "enabled": true,
          "scope": "page",
          "useRegex": true,
          "pattern": "^### (.+)$",
          "replacement": "## $1"
        }
      ]
    }
  }
}

Validation Rules

Copymarky validates rules to ensure they are well-formed:

id: Must be a non-empty string
enabled: Must be a boolean (true or false)
scope: Must be one of: "all", "selection", "page", "link"
useRegex: Must be a boolean
pattern: Must be a string (can be empty, but not recommended)
replacement: Must be a string (can be empty for deletion)

Regex validation: Invalid regular expressions will cause an error when the rule is applied. Test your regex syntax before saving.

Best Practices

Start Simple: Use literal rules (useRegex=false) first. Move to regex only when needed.
Test Pre and Post: Remember, pre-rules see HTML; post-rules see Markdown. The same pattern may behave differently.
Order Matters: Rules are applied in the order they appear. Earlier rules affect input to later rules.
Disable Before Deleting: Toggle enabled=false to test a rule’s effect without deleting it.
Use Scope: Apply rules only where needed (all/selection/page/link) to avoid unintended changes.
Document Complex Rules: Add a descriptive name (via rule ID) for rules you’ll reuse.

Text Replacements Guide - Practical examples and workflows
Settings Reference - Learn about pre and post configuration
Import & Export - Share and backup your rules

Text Replacement Rules Reference

What Are Text Replacements?

Rule Fields

Detailed Field Documentation

id

enabled

scope

useRegex

pattern

replacement

Example Rules

Example 1: Remove Ads (Literal)

Example 2: Normalize Headings (Regex)

Example 3: Remove URL Parameters (Regex)

Example 4: Convert Markdown Links to HTML (Regex)

Full Settings Example

Validation Rules

Best Practices

Related Guides