html-ast-transform

html-ast-transform

A set of helpers around parse5 for transforming HTML via an AST. Allows for flexible transformations useful for eg. processing rich text editor output for email.

Features

• Remove elements and their contents by blacklist
• Simple replacement of elements with string(s) or a function
• More complex transformations by reducing over child nodes, letting you add/remove/modify sibling nodes
• Utility functions to simplify creating nodes, adding and checking for attributes

Install

npm install --save html-ast-transform parse5

Usage

import transform, {h, getAttr, hasClass} from 'html-ast-transform'
// or es5:
var t = require('html-ast-transform')
var transform = t.default
// umd:
const {default: transform, h, hasClass, getAttr} = HtmlAstTransform


const result = transform(html, options)

Examples

Replace paragraph tags with table rows

const input = '<div><p class="text-center">Some text</p></div>'

const output = transform(input, {
  replaceTags: {
    p: node => h('tr', [], [
      h('td', node.attrs, node.childNodes)
    ])
  }
})

// output = '<div><tr><td class="text-center">Some text</td></tr></div>'

Generate plain text with links

const input = '<div><p>Some text with <a href="example.com">a link</a></p></div>'

const stringifyLinks = (acc, node) => {
  if (node.nodeName !== 'a') return acc.concat(node)

  const href = getAttr(node, 'href')
  return acc.concat(
    h('#text', `[${href}] `),
    node.childNodes
  )
}

const output = transform(input, {
  replaceTags: {
    div: '',
    p: '\n'
  },
  reduceAll: stringifyLinks
})

// output = '\nSome text with [example.com] a link'

API

transform

transform(input: string, {
  omitTags?: string[],
  replaceTags?: {
    [tagName: string]: string | string[] | (node: Node) => Node
  },
  reduceAll?: (acc: Node[], node: Node, index: number, nodes: Node[]) => Node[],
  fragment?: boolean
})

omitTags: An array of tag names that will be removed along with their contents

replaceTags: A mapping of tag names to their replacements. Replacements can be a string that will replace the opening tag, an array of strings that will replace opening and closing tags or a function that receives the node and returns its replacement.

reduceAll: A reducer to run over the children of all nodes. Receives the accumulated childNodes, the current childNode, the index and the list of childNodes.

fragment: Parse the input as an html fragment or full document. default = true.

Helpers

node factory

h(html: string): Node

h(type: string, value: string): TextNode | CommentNode

h(
  tagName: string,
  attrs: Attribute[],
  childNodes: Node[]
): Element

attribute helpers

// get the value of the named attribute, if present
getAttr(node: Element, name: string): string | undefined

// add an attribute to an element or update if it already exists
withAttr(node: Element, name: string, value: string): Element

// check if the element has a class
hasClass(node: Element, name: string): boolean

// add a class to an element if not already present
withClass(node: Element, name: string): Element