/posthtml

PostHTML is a tool to transform HTML/XML with JS plugins. By http://theprotein.io team.

Primary LanguageJavaScriptMIT LicenseMIT

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>

Directives

import posthtml from 'posthtml'

const php = `
  <component>
    <title><?php echo $title; ?></title>
    <text><?php echo $article; ?></text>
  </component>
`

const result = posthtml()
  .use(require('posthtml-custom-elements')())
  .process(html, {
    directives: [
      { name: '?php', start: '<', end: '>' }
    ]
  })
  .html

console.log(result)
<div class="component">
  <div class="title"><?php echo $title; ?></div>
  <div class="text"><?php echo $article; ?></div>
</div>
npm i posthtml-cli
"scripts": {
  "posthtml": "posthtml -o output.html -i input.html -c config.json"
}
npm run posthtml
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

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,
      }
    ]
  }
}
npm i -D html-loader posthtml-loader

v1.x

webpack.config.js

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

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 } 
          },
          {
            loader: 'posthtml-loader'
          }
        ]
      }
    ]
  },
  plugins: [
    new LoaderOptionsPlugin({
       options: {
         posthtml(ctx) {
          return {
            parser: require('posthtml-pug'),
            plugins: [
              require('posthtml-bem')()
            ]
          }
        }
      }
    })
  ]
}

export default config
$ npm i rollup-plugin-posthtml -D
# or
$ npm i rollup-plugin-posthtml-template -D
import { join } from 'path';

import posthtml from 'rollup-plugin-posthtml-template';
// or
// import posthtml from 'rollup-plugin-posthtml';

import sugarml from 'posthtml-sugarml';  // npm i posthtml-sugarml -D
import include from 'posthtml-include';  // npm i posthtml-include -D

export default {
  entry: join(__dirname, 'main.js'),
  dest: join(__dirname, 'bundle.js'),
  format: 'iife',
  plugins: [
    posthtml(
      parser: sugarml(),
      plugins: [include()],
      template: true  // only rollup-plugin-posthtml-template
    })
  ]
};

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

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)
posthtml-spaceless npm Remove whitespace between HTML tags
posthtml-cache npm Add a nanoid to links in you tags

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-tags npm Remove tags 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