Refactor version-replacer to substitution replacer and expand with more options

Author: josbeir

.vitepress/config.js

@@ -1,15 +1,18 @@
 import { defineConfig } from 'vitepress'
-import { versionReplacer } from './plugins/version-replacer.js'
+import { substitutionsReplacer } from './plugins/substitutions-replacer.js'
 import { deepMerge, loadConfigOverrides, applyBaseToHeadTags } from './utils.js'
 
 const defaultConfig = {
   srcDir: 'docs',
   title: 'CakePHP',
   description: 'CakePHP Documentation - The rapid development PHP framework',
   ignoreDeadLinks: true,
-  phpVersions: {
-    phpversion: '8.4',
-    minphpversion: '8.1'
+  substitutions: {
+    '|phpversion|': { value: '8.4', format: 'bold' },
+    '|minphpversion|': { value: '8.1', format: 'italic' },
+    // Add more substitutions here as needed
+    // '|cakeversion|': { value: '5.1', format: 'bold' },
+    // '|projectname|': 'CakePHP',  // Simple string without formatting
   },
   head: [
     ['link', { rel: 'icon', type: 'image/png', href: '/favicon/favicon-96x96.png', sizes: '96x96' }],
@@ -59,7 +62,7 @@ const mergedConfig = deepMerge(defaultConfig, overrides)
 
 // Configure markdown plugins after mergedConfig is available
 mergedConfig.markdown.config = (md) => {
-  md.use(versionReplacer, mergedConfig.phpVersions || {})
+  md.use(substitutionsReplacer, { substitutions: mergedConfig.substitutions || {} })
 }
 
 // Apply base path to head tags if base is specified

.vitepress/plugins/substitutions-replacer.js

@@ -0,0 +1,73 @@
+/**
+* Markdown-it plugin for replacing text placeholders
+*
+* Replaces custom placeholders like |phpversion| with configured values.
+* Supports optional formatting (bold, italic, code, or none).
+*/
+
+/**
+* Format a value based on the specified format type
+* @param {string} value - The value to format
+* @param {string} format - Format type: 'bold', 'italic', 'code', or 'none'
+* @returns {string} Formatted value
+*/
+function formatValue(value, format = 'none') {
+  switch (format) {
+    case 'bold':
+      return `**${value}**`
+    case 'italic':
+      return `*${value}*`
+    case 'code':
+      return `\`${value}\``
+    default:
+      return value
+  }
+}
+
+/**
+* Create a text substitution plugin
+* @param {Object} md - markdown-it instance
+* @param {Object} options - plugin options
+* @param {Object} options.substitutions - Object with placeholder keys and values
+* @param {string} options.phpversion - Legacy: Current PHP version (deprecated, use substitutions)
+* @param {string} options.minphpversion - Legacy: Minimum PHP version (deprecated, use substitutions)
+* @returns {void}
+*/
+export function substitutionsReplacer(md, options = {}) {
+  let substitutions = {}
+
+  // Support new substitutions format
+  if (options.substitutions) {
+    substitutions = options.substitutions
+  }
+  // Backward compatibility: convert old phpVersions format
+  else if (options.phpversion || options.minphpversion) {
+    substitutions = {
+      '|phpversion|': { value: options.phpversion || '8.4', format: 'bold' },
+      '|minphpversion|': { value: options.minphpversion || '8.1', format: 'italic' }
+    }
+  }
+
+  // Store original render method
+  const originalRender = md.render.bind(md)
+
+  md.render = function(src, env = {}) {
+    // Process each substitution
+    for (const [placeholder, config] of Object.entries(substitutions)) {
+      // Support both simple string values and objects with format options
+      const value = typeof config === 'string' ? config : config.value
+      const format = typeof config === 'object' && config.format ? config.format : 'none'
+
+      // Create regex to match the placeholder (escape special regex characters)
+      const escapedPlaceholder = placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const regex = new RegExp(escapedPlaceholder, 'g')
+
+      // Replace with formatted value
+      src = src.replace(regex, formatValue(value, format))
+    }
+
+    return originalRender(src, env)
+  }
+}
+
+export default substitutionsReplacer

.vitepress/plugins/version-replacer.js

@@ -77,6 +77,30 @@ export default {
 
 All markdown documentation files should be placed in the `docs/` directory.
 
+### Text Substitutions
+
+You can use placeholders in your markdown files that will be automatically replaced with configured values. This is useful for version numbers or other values that need to be updated across multiple files.
+
+**Configuration** (`config.js`):
+
+```javascript
+export default {
+  substitutions: {
+    '|phpversion|': { value: '8.4', format: 'bold' },
+    '|minphpversion|': { value: '8.1', format: 'italic' },
+    '|myversion|': '1.0.0'  // Simple string without formatting
+  }
+}
+```
+
+**Usage in Markdown**:
+
+```markdown
+This plugin requires PHP |phpversion| or higher (minimum |minphpversion|).
+```
+
+**Result**: This plugin requires PHP **8.4** or higher (minimum *8.1*).
+
 ## Project Structure
 
 ```