https://github.com/phtmlorg/phtml

Transform HTML with JavaScript
https://github.com/phtmlorg/phtml

Last synced: about 18 hours ago
JSON representation

Transform HTML with JavaScript

• Host: GitHub
• URL: https://github.com/phtmlorg/phtml
• Owner: phtmlorg
• License: cc0-1.0
• Created: 2018-05-26T20:29:06.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2020-08-20T08:19:25.000Z (about 4 years ago)
• Last Synced: 2024-10-13T18:18:00.366Z (about 1 month ago)
• Language: JavaScript
• Homepage: https://phtml.io
• Size: 211 KB
• Stars: 68
• Watchers: 5
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# phtml [][phtml]

[![NPM Version][npm-img]][npm-url]

[![Build Status][cli-img]][cli-url]

[![Support Chat][git-img]][git-url]

[phtml] is a tool for transforming HTML with JavaScript.

It fully embraces the HTML language, and aims to help you write and maintain

HTML that you _and future you_ feel good about.

phtml helps you compose [reusable templates and components](https://github.com/phtmlorg/phtml-template),

or automate [image size attributes](https://github.com/phtmlorg/phtml-image-size)

and [schema.org microdata](https://github.com/phtmlorg/phtml-schema) and [heading levels](https://github.com/phtmlorg/phtml-h-element),

or transform modern [CSS with PostCSS](https://github.com/phtmlorg/phtml-css)

and [JS with Babel](https://github.com/phtmlorg/phtml-js).

It works in the command line and Node, but also [Grunt], [Gulp],

[11ty][11ty], [Webpack], [Rollup], and even

[the browser itself][browser].

## Usage

Transform HTML files directly from the command line:

```bash

npx phtml source.html output.html

```

Include plugins directly from the command line:

```bash

npx phtml source.html output.html -p @phtml/markdown,@phtml/image-alt

```

Transform strings from the command line:

```bash

echo "
phtml **Markdown**
" | npx phtml -p @phtml/markdown


# 
phtml Markdown



```


### Node

Add [phtml] to your build tool:

```bash

npm install phtml --save-dev

```

Use [phtml] to process your HTML:

```js

const phtml = require('phtml');

phtml.process(YOUR_HTML, /* processOptions */, /* pluginOrPlugins */);

```

#### Node Example

```js

const phtml = require('phtml');

const html = `

  Super Title

  Awesome Text

`;

phtml.process(html, { from: 'my-component.html' }).then(console.log);

/* Result {

  from: 'component.html',

  to: 'component.html',

  root: Fragment {

    name: '#document-fragment',

    nodes: NodeList [

      Element {

        name: "my-component",

        attrs: AttributeList [

          { name: "class", value: "main" }

        ],

        nodes: NodeList [

          Text "\n  ",

          Element {

            name: "title",

            nodes: NodeList [

              Text "Super Title"

            ]

          },

          Text "\n  ",

          Element {

            name: "text",

            nodes: NodeList [

              Text "Awesome Text"

            ]

          },

          Text "\n"

        ]

      }

    ]

  }

}

```

#### Using Plugins in Node

Add a [phtml] Plugin to your build tool:

```bash

npm install phtml-some-thing --save-dev

```

```js

const phtml = require('phtml');

const postHtmlSomeThing = require('phtml-some-thing');

phtml.use(

  postHtmlSomeThing(/* pluginOptions */)

).process(YOUR_HTML);

```

## Plugins

You can find phtml plugins on npm.

https://www.npmjs.com/search?q=keywords:phtml-plugin

### Plugin Creation

Create plugins directly from the command line:

```bash

npm init phtml-plugin

# Plugin Name: Example (becomes `phtml Hello` / `phtml-hello`)

# Keywords: awesome,blossom (added to package.json keywords)

```

Once the command finishes, a new plugin is fully scaffolded with bare

functionality, documentation, and tests. Within the plugin directory,

functionality is added to `src/index.js`.

#### Advanced Plugin Creation

Create plugins using a new `Plugin` class:

```js

import phtml from 'phtml';

export default new phtml.Plugin('phtml-hello', pluginOptions => {

	// initialization logic

  return {

    Element(element, result) {

      // runtime logic, do something with an element

    },

    Root(root, result) {

      // runtime logic, do something with the root

    }

  };

});

```

The runtime plugin can visit nodes as they are entered or exited.

## Browser Usage

phtml works in the browser, which may be great for experimentation:

```html

const html = `<my-component class="main">

  <title>Super Title</title>

  <text>Awesome Text</text>

</my-component>`;

phtml.process(html, { from: 'my-component.html' }).then(console.log);

```

Note that the browser version of phtml is 52 kB because it includes its own

HTML parser, [parse5].

[cli-img]: https://img.shields.io/travis/phtmlorg/phtml.svg

[cli-url]: https://travis-ci.org/phtmlorg/phtml

[git-img]: https://img.shields.io/badge/support-chat-blue.svg

[git-url]: https://gitter.im/postcss/postcss

[npm-img]: https://img.shields.io/npm/v/phtml.svg

[npm-url]: https://www.npmjs.com/package/phtml

[11ty]: https://github.com/phtmlorg/phtml-11ty

[browser]: https://unpkg.com/phtml/

[Grunt]: https://github.com/phtmlorg/grunt-phtml

[Gulp]: https://github.com/phtmlorg/gulp-phtml

[parse5]: https://github.com/inikulin/parse5

[phtml]: https://github.com/phtmlorg/phtml

[Rollup]: https://github.com/phtmlorg/rollup-plugin-phtml

[Webpack]: https://github.com/phtmlorg/phtml-loader