Adam Piontek 3eff955672 progress on migrating to heex templates and font-icons

2022-08-13 07:32:36 -04:00

23 KiB

Raw Blame History

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>

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		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

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)

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

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-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
posthtml-email-remove-unused-css		Remove unused CSS from email templates

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