node package manager
Don’t reinvent the wheel. Reuse code within your team. Create a free org »

posthtml

NPM Deps Tests Coverage Standard Code Style Chat

PostHTML

PostHTML is a tool for transforming HTML/XML with JS plugins. PostHTML itself is very small. It includes only a HTML parser, a HTML node tree API and a node tree stringifier.

All HTML transformations are made by plugins. And these plugins are just small plain JS functions, which receive a HTML node tree, transform it, and return a modified tree.

For more detailed information about PostHTML in general take a look at the docs.

Dependencies

Name Status Description
posthtml-parser npm Parser HTML/XML to PostHTMLTree
posthtml-render npm Render PostHTMLTree to HTML/XML

Install

npm i -D posthtml

Usage

API

Sync

import posthtml from 'posthtml'
 
const html = `
  <component>
    <title>Super Title</title>
    <text>Awesome Text</text>
  </component>
`
 
const result = posthtml()
  .use(require('posthtml-custom-elements')())
  .process(html, { sync: true })
  .html
 
console.log(result)
<div class="component">
  <div class="title">Super Title</div>
  <div class="text">Awesome Text</div>
</div>

⚠️ Async Plugins can't be used in sync mode and will throw an Error. It's recommended to use PostHTML asynchronously whenever possible.

Async

import posthtml from 'posthtml'
 
const html = `
  <html>
    <body>
      <p class="wow">OMG</p>
    </body>
  </html>
`
 
posthtml(
  [
    require('posthtml-to-svg-tags')(),
    require('posthtml-extend-attrs')({
      attrsTree: {
        '.wow' : {
          id: 'wow_id',
          fill: '#4A83B4',
          'fill-rule': 'evenodd',
          'font-family': 'Verdana'
        }
      }
    })
  ])
  .process(html/*, options */)
  .then((result) =>  console.log(result.html))
<svg xmlns="http://www.w3.org/2000/svg">
  <text
    class="wow"
    id="wow_id"
    fill="#4A83B4"
    fill-rule="evenodd" font-family="Verdana">
      OMG
  </text>
</svg>

CLI

npm i posthtml-cli
"scripts"{
  "posthtml": "posthtml -o output.html -i input.html -c config.json"
}
npm run posthtml

Gulp

npm i -D gulp-posthtml
import tap from 'gulp-tap'
import posthtml from 'gulp-posthtml'
import { task, src, dest } from 'gulp'
 
task('html', () => {
  let path
 
  const plugins = [ require('posthtml-include')({ root: `${path}` }) ]
  const options = {}
 
  src('src/**/*.html')
    .pipe(tap((file) => path = file.path))
    .pipe(posthtml(plugins, options))
    .pipe(dest('build/'))
})

Check project-stub for an example with Gulp

Grunt

npm i -D grunt-posthtml
posthtml: {
  options: {
    use: [
      require('posthtml-doctype')({ doctype: 'HTML 5' }),
      require('posthtml-include')({ root: './', encoding: 'utf-8' })
    ]
  },
  build: {
    files: [
      {
        dot: true,
        cwd: 'html/',
        src: ['*.html'],
        dest: 'tmp/',
        expand: true,
      }
    ]
  }
}

Webpack

npm i -D html-loader posthtml-loader

v1.x

webpack.config.js

const config = {
  module: {
    loaders: [
      {
        test: /\.html$/,
        loader: 'html!posthtml'
      }
    ]
  }
  posthtml: (ctx) => {
    return {
      parser: require('posthtml-pug')
      plugins: [
        require('posthtml-include')({ root: ctx.resourcePath })
      ]
    }
  }
}
 
export default config

v2.x

webpack.config.js

import { LoaderOptionsPlugin } from 'webpack'
 
const config = {
  module: {
    rules: [
      {
        test: /\.html$/,
        use: [
          { loader: 'html-loader', options: { minimize: true } }
          'posthtml-loader'
        ]
      }
    ]
  }
  plugins: [
    new LoaderOptionsPlugin({
       options: {
         posthtml (ctx) {
          parser: require('posthtml-pug')
          plugins: [
            require('posthtml-include')({ root: ctx.resourcePath }) }
          ]
        }
      }
    })
  ]
}
 
export default config

Parser

import pug from 'posthtml-pug'
 
posthtml().process(html, { parser: pug(options) }).then((result) => result.html)
Name Status Description
posthtml-pug npm Pug Parser
sugarml npm SugarML Parser

Plugins

In case you want to develop your own plugin, we recommend using posthtml-plugin-boilerplate for getting started.

TEXT

Name Status Description
posthtml-md npm Easily use context-sensitive markdown within HTML
posthtml-lorem npm Add lorem ipsum placeholder text to any document
posthtml-retext npm Extensible system for analysing and manipulating natural language

HTML

Name Status Description
posthtml-doctype npm Set !DOCTYPE
posthtml-head-elements npm Include head elements from JSON file
posthtml-include npm Include HTML
posthtml-modules npm Include and process HTML
posthtml-extend npm Extend Layout (Pug-like)
posthtml-extend-attrs npm Extend Attrs
posthtml-expressions npm Template Expressions
posthtml-inline-assets npm Inline external scripts, styles, and images
posthtml-static-react npm Render custom elements as static React components
posthtml-custom-elements npm Use custom elements
posthtml-web-component npm Web Component server-side rendering, Component as a Service (CaaS)

CSS

Name Status Description
posthtml-bem npm Support BEM naming in html structure
posthtml-postcss npm Use PostCSS in HTML document
posthtml-px2rem npm Change px to rem in Inline CSS
posthtml-css-modules npm Use CSS modules in HTML
posthtml-postcss-modules npm CSS Modules in html
posthtml-classes npm Get a list of classes from HTML
posthtml-prefix-class npm Prefix class names
posthtml-modular-css npm Make CSS modular
posthtml-inline-css npm CSS Inliner
posthtml-collect-styles npm Collect styles from html and put it in the head
posthtml-collect-inline-styles npm Collect inline styles and insert to head tag
posthtml-style-to-file npm Save HTML style nodes and attributes to CSS file
posthtml-color-shorthand-hex-to-six-digit npm Enforce all hex color codes to be 6-char long

IMG & SVG

Name Status Description
posthtml-img-autosize npm Auto setting the width and height of <img>
posthtml-to-svg-tags npm Convert html tags to svg equals
posthtml-webp npm Add WebP support for images

Accessibility

Name Status Description
posthtml-aria-tabs npm Write accessible tabs with minimal markup
posthtml-alt-always npm Always add alt attribute for images that don't have it
posthtml-schemas npm Add microdata to your HTML

Optimization

Name Status Description
posthtml-shorten npm Shorten URLs in HTML
posthtml-uglify npm Shorten CSS in HTML
posthtml-minifier npm Minify HTML
posthtml-remove-attributes npm Remove attributes unconditionally or with content match
posthtml-remove-duplicates npm Remove duplicate elements from your html
posthtml-transformer npm Process HTML by directives in node attrs, such as inline scripts and styles, remove useless tags, concat scripts and styles etc.
htmlnano npm HTML Minifier
posthtml-email-remove-unused-css npm Remove unused CSS from email templates

Workflow

Name Status Description
posthtml-load-plugins npm Autoload Plugins
posthtml-load-options npm Autoload Options (Parser && Render)
posthtml-load-config npm Autoload Config (Plugins && Options)
posthtml-w3c npm Validate HTML with W3C Validation
posthtml-hint npm Lint HTML with HTML Hint
posthtml-tidy npm Sanitize HTML with HTML Tidy

Middleware

Name Status Description
koa-posthtml npm Koa Middleware
hapi-posthtml npm Hapi Plugin
express-posthtml npm Express Middleware
electron-posthtml npm Electron Plugin
metalsmith-posthtml npm Metalsmith Plugin

Maintainers


Ivan Voischev

Anton Winogradov

Alexej Yaroshevich

Vasiliy

Contributing

See PostHTML Guidelines and CONTRIBUTING.

LICENSE

MIT