posthtml-plugin-util

Posthtml Plugin Util

A little set of utilities for posthtml plugins

Note: This project is in early development, and versioning is a little different. Read this for more details.

Installation

npm install posthtml-plugin-util -S

Note: This project is compatible with node v6+ only

Usage

This is just a small utility that contains a couple a useful functions when developing posthtml plugins.

modifyNodes(tree, match, transform)

Given a posthtml AST, a function that will return any node that matches given criteria, and a function that receives matched nodes and returns one or more modified nodes, returns a modified AST.

Example: Using modifyNodes to modify a node's content

const util = require('posthtml-plugin-util')

module.exports = function yellPlugin (tree) {
  return util.modifyNodes(tree, (node) => node.name === 'p', (node) => {
    node.content = node.content.map((n) => n.content = n.content.toUpperCase())
    return node
  })
}

Input:

<p>hello world!</p>

Output:

<p>HELLO WORLD!</p>

Example: Using modifyNodes to remove a node

const util = require('posthtml-plugin-util')

module.exports = function removeNodePlugin (tree) {
  return util.modifyNodes(tree, (node) => node.name === 'remove', (node) => {
    return null
  })
}

Input:

<p>before</p>
<remove>hello world!</remove>
<p>after</p>

Output:

<p>before</p>
<p>after</p>

Example: Using modifyNodes to add extra nodes

const util = require('posthtml-plugin-util')

module.exports = function echoPlugin (tree) {
  return util.modifyNodes(tree, (node) => node.name === 'echo', (node) => {
    if (!node.attrs) node.attrs = {}
    if (!node.attrs.class) node.attrs.class = []
    node.attrs.class.push('echo')
    node.name = 'div'
    return [node, node]
  })
}

Input:

<p>before</p>
<echo>echo</echo>
<p>after</p>

Output:

<p>before</p>
<div class='echo'>echo</div>
<div class='echo'>echo</div>
<p>after</p>

validateNode(node)

Given a single posthtml AST node, checks it for formatting errors. Example:

const util = require('posthtml-plugin-util')

util.validateNode({
  type: 'text',
  content: ['foo', 'bar'],
  location: { line: 1, col: 1 }
})

// => Error: text node content must be a string
//    From: plugin-util
//    Node: {
//      type: 'text',
//      content: ['foo', 'bar'],
//      location: { line: 1, col: 1 }
//    }

validateTree(tree)

Recursively validates each node in a given posthtml AST tree.

const util = require('posthtml-plugin-util')

util.validateNode({
  type: 'tag',
  name: 'div'
  content: [
    {
      content: 'foo',
      location: { line: 1, col: 4 }
    }
  ],
  location: { line: 1, col: 1 }
})

// => Error: node missing "type" attribute
//    From: plugin-util
//    Node: {
//      content: 'foo',
//      location: { line: 1, col: 4}
//    }

License & Contributing

• Details on the license can be found here
• Details on running tests and contributing can be found here