Skip to content

Latest commit

 

History

History
160 lines (142 loc) · 5.34 KB

README.md

File metadata and controls

160 lines (142 loc) · 5.34 KB
Raw

metalsmith-one-replace

A single Metalsmith/markdown plugin to perform multiple types of replace action within markdown files. The supported replace functions are:

  • Insert content from other file
  • Variable substitution
  • Regex replacement
  • Replace tags with strings build by a pattern

The default tags (override by defining custom regular expression in keyRegex config attribute) are :

  • {#insert ...} - to insert a file
  • {#var ...} - for variable substitution
  • {#banner ...} - to insert set of HTML tags based on pattern

For detailed usage, refer to wiki.

Installation

$ npm install metalsmith-one-replace

Config

Example - Simple (to insert file using {#insert} custom tag)

...
{
    actions:[{
        type:'file'
    }]
}
...

Example - Simple (to substitute variable using {#var} custom tag})

...
{
    actions:[{
        type:'var',
        varValues:{
            'f1':'Apple',
            'f2':'Orange'
        }
    }]
}
...

Example - Simple (defining custom tag {#img} to use instead of within markdown files)

...
{
    actions:[{
        type:'replace',
        fileFilter:'.md$',
        replacePatterns:{
            '{#img (.*?)}':'<img $1>'
        }
    }]
}
...

Example - Simple (defining custom tag {#img} to use instead of within markdown files)

...
{
    actions:[{
        type:'build',
        fileFilter:'.md$',
        outerBody:'<div class="banner">{{innerBody}}</div>',
        innerBody:'<div class="banner-item"><div class="item-box"><a href="{{1}}"><div class="item-box-image"><img src="{{2}}"></div><div class="item-box-title">{{0}}</div><div class="item-box-desc">{{3}}</div></a></div></div>'
    }]
}
...

Example - Detailed

...
{
    consoleLog: false,
    enabled: true,
    actions: [{
        priority: 10,
        type:'file'
    },{
        priority: 20,
        type:'var',
        varValues:{
            'f1':'Apple',
            'f2':'Orange',
            'f3':'Banana'
        }
    },{
        priority: 1,
        type:'replace',
        fileFilter:'.svg$',
        replacePatterns:{
            '\<![ \r\n\t]*(--([^\-]|[\r\n]|-[^\-])*--[ \r\n\t]*)\>':'',
            '(xml([a-z:-A-Z0-9]+))=[\"]?((?:.(?![\"]?\s+(?:\S+)=|[>\"]))+.)[\"]?([ ]+)?':'',
            '^\s*$':'',
            '<(([a-z]+)*[^>]+)\/>':'<$1></$2>',
            '([a-z:-A-Z0-9]+)="null"?([ ]+)?':''
        }
    },{
        enabled: false,
        priority:5,
        type:'replace',
        fileFilter:'.md$',
        replacePatterns:{
            '{#img (.*?)}':'<img $1>',
            '{#bold (.*?)}':'<b>$1</b>'
        }
    },{
        enabled: true,
        priority:5,
        type:'build',
        fileFilter:'.md$',
        tag:'^{#banner (.*)}',
        outerBody:'<div class="banner">{{innerBody}}</div>',
        innerBody:'<div class="banner-item"><div class="item-box"><a href="{{1}}"><div class="item-box-image"><img src="{{2}}"></div><div class="item-box-title">{{0}}</div><div class="item-box-desc">{{3}}</div></a></div></div>'
    }]
}
...

More information about config attributes:

  • consoleLog (optional boolean default:false) - to log the info to console
  • enabled (optional boolean default:true) - to enable/disable the entire plugin
  • actions (array of action objects) is mandatory
    • priority (optional number) - to specify the sequence order while processing
    • enabled (optional boolean default:true) - to enable/disable a specific action
    • fileFilter (optional regex string default:(.*?)) - to filter files for processing under a specific action
    • type (string values are var, file, replace and build) is mandatory - to specify the routine while processing
      • attributes when type is var
        • keyRegex (optional regex string default:{#var (.*?)}) - regex to find the tag (example {#var}) with the variable name as the parameter
        • varValues (key-value pair object) is mandatory - with variable name and it's value as key-value pair
        • ignoreMissing (optional boolean default:false) - ignore (by substituting it with blank) if the variable is not defined
      • attributes when type is file
        • keyRegex (optional regex string default:^{#insert (.*)}) - regex to find the tag (example {#insert}) with the name of the file (with path) as parameter
        • ignoreMissing (optional boolean default:false) - ignore (by substituting it with blank) if the file is not found
        • removeFile (optional boolean default:true) - remove the file from target folder after inserting the content
      • attributes when type is replace
        • replacePatterns (key-value pair object) is mandatory - regex find and replace string as key-value pair
      • attributes when type is build
        • tag (optional regex string default:^{#banner (.*)}) = regex to find the tag (example {#banner} with the JSON object as parameter)
        • outerBody - string containing HTML tags (to be used once)
        • innerBody - string containing HTML tags with {{}} placeholders. Based on the elements of JSON object specified as the parameter, that many times this string will be duplicated, and {{}} placeholders will be replaced with the value of array within the JSON object.

Documentation

Refer to the wiki

License

MIT