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		Parser HTML/XML to PostHTMLTree
posthtml-render		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>

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) => ({
      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

Rollup

$ 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		Pug Parser
sugarml		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		Easily use context-sensitive markdown within HTML
posthtml-lorem		Add lorem ipsum placeholder text to any document
posthtml-retext		Extensible system for analysing and manipulating natural language
prevent-widows		Prevent widows from appearing at the end of paragraphs

HTML

Name	Status	Description
posthtml-doctype		Set !DOCTYPE
posthtml-head-elements		Include head elements from JSON file
posthtml-include		Include HTML
posthtml-modules		Include and process HTML
posthtml-extend		Extend Layout (Pug-like)
posthtml-extend-attrs		Extend Attrs
posthtml-expressions		Template Expressions
posthtml-inline-assets		Inline external scripts, styles, and images
posthtml-static-react		Render custom elements as static React components
posthtml-custom-elements		Use custom elements
posthtml-web-component		Web Component server-side rendering, Component as a Service (CaaS)
posthtml-spaceless		Remove whitespace between HTML tags
posthtml-cache		Add a nanoid to links in you tags
posthtml-highlight		Syntax highlight code elements

CSS

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

IMG & SVG

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

Accessibility

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

Optimization

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

Workflow

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

Middleware

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

Maintainers

Ivan Voischev

Anton Winogradov

Alexej Yaroshevich

Vasiliy

Contributing

See PostHTML Guidelines and CONTRIBUTING.

LICENSE

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 419 Commits
.github		.github
docs		docs
lib		lib
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
logo.svg		logo.svg
package.json		package.json

License

simonlc/posthtml

Folders and files

Latest commit

History

Repository files navigation