html-ast-transform
v2.0.1
Published
Flexible html transformations by mapping/reducing an AST
Downloads
621
Readme
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
- Strip tags or nodes
- Replace nodes with string(s) or a function
- Reduce child nodes for adding/removing/modifying 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 transform = require('html-ast-transform').transform
// umd:
const {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 version retaining links and image alt text
const input = '<p>Text with <a href="example.com">a link</a><img alt="and an image" /></p>'
const stringifyLinks = (acc, node) => {
if (node.nodeName !== 'a') return acc.concat(node)
const href = getAttr(node, 'href')
return acc.concat(
node.childNodes,
h('#text', ` [${href}]`)
)
}
const getAltText = node => {
const alt = getAttr(node, 'alt')
return h('#text', alt ? ` [${alt}]` : '')
}
const output = transform(input, {
replaceTags: {
p: '\n',
img: getAltText
},
reduceAll: stringifyLinks
})
// output = '\nText with a link [example.com] [and an image]'
API
transform
transform(input: string, {
replaceTags?: {
[tagName: string]: string | string[] | (node: Element) => Node
},
reduceAll?: (acc: Node[], node: Element, index: number, nodes: Node[]) => Node[],
stripContent?: string[],
stripTags?: string[],
trimWhitespace?: boolean,
fragment?: boolean
})
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 a replacement node.
reduceAll: A reducer to run over the children of all nodes. Receives the accumulated childNodes, the current childNode, the current index and the list of childNodes.
stripContent: An array of tag names that will be removed along with their contents
stripTags An array of tag names to be removed while retaining their contents
trimWhitespace: Handle indentation and newlines by removing whitespace only text nodes and trimming text nodes with multiple leading/trailing whitespace to a single space. default = true
fragment: Parse the input as an html fragment rather than a 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