md-fixup Apex Plugin

This plugin integrates md-fixup with Apex, allowing you to apply custom text replacements from a file stored in the plugin's support directory.

Prerequisites

• md-fixup must be installed and available in your PATH
  • Install from: https://github.com/ttscoff/md-fixup
  • This plugin uses the Rust binary version (not the Python version)
  • Ensure md-fixup is in your PATH: which md-fixup

Installation

The plugin is already installed in ~/.config/apex/plugins/md-fixup. To enable it:

1. Verify the plugin is recognized:

   apex --list-plugins

2. Enable the plugin (if not already enabled):

   apex --enable-plugin md-fixup

Setup

1. Create the Replacements File

The plugin looks for a replacements file at:

~/.config/apex/support/md-fixup/replacements.yml

If this file doesn't exist, the plugin will create a template YAML file on first run.

2. Configure Replacements

Edit the replacements file with your custom search/replace patterns. The file uses YAML format with a replacements: array. Each replacement has:

• name: A descriptive name for the replacement
• pattern: A regex pattern to match
• replacement: The replacement text (can use regex groups like $1, $2)
• timing: When to apply (before or after other processing)
• in_code_blocks: Whether to apply inside code blocks (true/false)
• in_frontmatter: Whether to apply in frontmatter (true/false)

Example replacements.yml:

replacements:
  - name: "fix-double-spaces"
    pattern: "  +"
    replacement: " "
    timing: after
    in_code_blocks: false
    in_frontmatter: false

  - name: "normalize-http"
    pattern: "http://"
    replacement: "https://"
    timing: after
    in_code_blocks: false
    in_frontmatter: false

See the md-fixup documentation for more details on the replacements file format.

3. Test the Plugin

Test the plugin with a sample markdown file:

echo "This is a test with foo in it." | apex --mode kramdown

If your replacements file contains a replacement with pattern foo and replacement bar, the output should show "bar" instead of "foo".

Usage

Once enabled, the plugin automatically runs during the pre_parse phase for all markdown processed by Apex. No additional configuration is needed.

Disabling the Plugin

To temporarily disable the plugin:

apex --disable-plugin md-fixup

Uninstalling the Plugin

To remove the plugin:

apex --uninstall-plugin md-fixup

Note: This removes the plugin directory but leaves the support data (including your replacements file) intact at ~/.config/apex/support/md-fixup/.

Troubleshooting

md-fixup not found

If you see an error that md-fixup is not found:

1. Verify it's installed: which md-fixup
2. Ensure it's in your PATH
3. Check that you're using the Rust binary version, not Python

Replacements not working

1. Check that the replacements file exists: ~/.config/apex/support/md-fixup/replacements.yml
2. Verify the YAML format is correct (use a YAML validator if needed)
3. Check that the regex patterns are correct
4. Check plugin logs or run Apex with verbose output

Plugin not running

1. Verify the plugin is enabled: apex --list-plugins
2. Check that the script is executable: ls -l ~/.config/apex/plugins/md-fixup/md-fixup.sh
3. Ensure jq is installed (required for JSON parsing):
   • macOS: brew install jq
   • Linux: apt-get install jq (or equivalent for your distribution)
   • The script has a basic fallback if jq is not available, but jq is recommended

md-fixup --replacements-file not supported

If you see a warning that --replacements-file is not supported, it may mean:

1. Your version of md-fixup doesn't support this flag yet
2. The flag name is different in your version
3. Check md-fixup --help to see available options

The plugin will fall back to running md-fixup without the replacements file if the flag is not recognized.

Plugin Details

• Phase: pre_parse (runs before markdown parsing)
• Priority: 50 (runs early in the pre_parse phase)
• Timeout: 5000ms (5 seconds)

Support Directory

The plugin uses Apex's support directory system:

• Base: ~/.config/apex/support/ (or $XDG_CONFIG_HOME/apex/support/)
• Plugin-specific: ~/.config/apex/support/md-fixup/
• Replacements file: ~/.config/apex/support/md-fixup/replacements.yml

This directory is created automatically if it doesn't exist.

Environment Variables

The plugin has access to these Apex-provided environment variables:

• APEX_PLUGIN_DIR - Path to the plugin directory
• APEX_SUPPORT_DIR - Base support directory (plugin-specific subdirectory is appended)
• APEX_FILE_PATH - Path to the file being processed (if available)

License

This plugin is provided as-is. Refer to the md-fixup project for its license terms.