[![NPM][npm]][npm-url] [![Deps][deps]][deps-url] [![Tests][build]][build-url] [![Coverage][cover]][cover-url] [![Standard Code Style][code-style]][code-style-url] [![Twitter][twitter]][twitter-url] # 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][docs-url]. ### Dependencies | Name | Status | Description | |:----:|:------:|:-----------:| |[posthtml-parser][parser]|[![npm][parser-badge]][parser-npm]| Parser HTML/XML to PostHTMLTree | |[posthtml-render][render]|[![npm][render-badge]][render-npm]| Render PostHTMLTree to HTML/XML | [docs]: https://github.com/posthtml/posthtml/blob/master/docs [parser]: https://github.com/posthtml/posthtml-parser [parser-badge]: https://img.shields.io/npm/v/posthtml-parser.svg [parser-npm]: https://npmjs.com/package/posthtml-parser [render]: https://github.com/posthtml/posthtml-render [render-badge]: https://img.shields.io/npm/v/posthtml-render.svg [render-npm]: https://npmjs.com/package/posthtml-render ## Create to your project ```bash npm init posthtml ``` ## Install ```bash npm i -D posthtml ``` ## Usage ### API **Sync** ```js import posthtml from 'posthtml' const html = ` Super Title Awesome Text ` const result = posthtml() .use(require('posthtml-custom-elements')()) .process(html, { sync: true }) .html console.log(result) ``` ```html
Super Title
Awesome Text
``` > :warning: Async Plugins can't be used in sync mode and will throw an Error. It's recommended to use PostHTML asynchronously whenever possible. **Async** ```js import posthtml from 'posthtml' const html = `

OMG

` 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)) ``` ```html OMG ``` **Directives** ```js import posthtml from 'posthtml' const php = ` <?php echo $title; ?> ` const result = posthtml() .use(require('posthtml-custom-elements')()) .process(html, { directives: [ { name: '?php', start: '<', end: '>' } ] }) .html console.log(result) ``` ```html
``` ### [CLI](https://npmjs.com/package/posthtml-cli) ```bash npm i posthtml-cli ``` ```json "scripts": { "posthtml": "posthtml -o output.html -i input.html -c config.json" } ``` ```bash npm run posthtml ``` ### [Gulp](https://gulpjs.com) ```bash npm i -D gulp-posthtml ``` ```js 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](https://github.com/posthtml/project-stub) for an example with Gulp ### [Grunt](https://gruntjs.com) ```bash npm i -D grunt-posthtml ``` ```js 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](https://webpack.js.org) ```bash npm i -D html-loader posthtml-loader ``` #### v1.x **webpack.config.js** ```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** ```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](https://rollupjs.org/) ```bash $ npm i rollup-plugin-posthtml -D # or $ npm i rollup-plugin-posthtml-template -D ``` ```js 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 ```js import pug from 'posthtml-pug' posthtml().process(html, { parser: pug(options) }).then((result) => result.html) ``` | Name |Status|Description| |:-----|:-----|:----------| |[posthtml-pug][pug]|[![npm][pug-badge]][pug-npm]|Pug Parser| |[sugarml][sugar]|[![npm][sugar-badge]][sugar-npm]|SugarML Parser| [pug]: https://github.com/posthtml/posthtml-pug [pug-badge]: https://img.shields.io/npm/v/posthtml-pug.svg [pug-npm]: https://npmjs.com/package/posthtml-pug [sugar]: https://github.com/posthtml/sugarml [sugar-badge]: https://img.shields.io/npm/v/sugarml.svg [sugar-npm]: https://npmjs.com/package/sugarml ## Plugins In case you want to develop your own plugin, we recommend using [posthtml-plugin-starter][plugin] to get started. - [posthtml-plugins](http://maltsev.github.io/posthtml-plugins) - [awesome-posthtml](https://github.com/posthtml/awesome-posthtml) [plugin]: https://github.com/posthtml/posthtml-plugin-starter ## Maintainers

Ivan Demidov

Ivan Voischev
## Contributors ## Backers Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/posthtml#backer)] [npm]: https://img.shields.io/npm/v/posthtml.svg [npm-url]: https://npmjs.com/package/posthtml [deps]: https://david-dm.org/posthtml/posthtml.svg [deps-url]: https://david-dm.org/posthtml/posthtml [build]: https://github.com/posthtml/posthtml/workflows/Actions%20Status/badge.svg?style=flat-square [build-url]: https://github.com/posthtml/posthtml/actions?query=workflow%3A%22CI+tests%22 [cover]: https://coveralls.io/repos/posthtml/posthtml/badge.svg?branch=master [cover-url]: https://coveralls.io/r/posthtml/posthtml?branch=master [code-style]: https://img.shields.io/badge/code%20style-standard-yellow.svg [code-style-url]: http://standardjs.com/ [twitter]: https://badgen.net/twitter/follow/posthtml [twitter-url]: https://twitter.com/PostHTML [chat]: https://badges.gitter.im/posthtml/PostHTML.svg [chat-url]: https://gitter.im/posthtml/posthtml?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge" [docs-url]: https://github.com/posthtml/posthtml/tree/master/docs