# phtml

> A tool for transforming HTML with JavaScript

Latest version **4.1.0** (published 2019-05-17) · CC0-1.0 license · 0 weekly downloads

## Install

```sh
npm install phtml
pnpm add phtml
yarn add phtml
bun add phtml
```

Provides the command `phtml`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.0 |
| Published | 2019-05-17 |
| First published | 2019-02-10 |
| Weekly downloads | 0 |
| License | CC0-1.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=8.0.0 |
| Dependencies | 1 |
| Unpacked size | 987 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 67 |
| Author | Jonathan Neal |
| Maintainers | jonathantneal |
| Keywords | phtml, html |

## Links

- npm: https://www.npmjs.com/package/phtml
- Repository: https://github.com/jonathantneal/phtml
- Homepage: https://github.com/phtmlorg/phtml#readme
- Issues: https://github.com/phtmlorg/phtml/issues
- npm.io page: https://npm.io/package/phtml

## Dependencies (1)

- [parse5](https://npm.io/package/parse5.md) ^5.1.0

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 4.1.0 (latest) — 2019-05-17
- 4.0.0 — 2019-05-06
- 3.3.1 — 2019-05-04
- 3.3.0 — 2019-05-03
- 3.2.1 — 2019-04-22
- 3.2.0 — 2019-04-22
- 3.1.0 — 2019-04-19
- 3.0.0 — 2019-03-16
- 2.0.4 — 2019-03-11
- 2.0.3 — 2019-03-09
- 2.0.2 — 2019-02-25
- 2.0.1 — 2019-02-19
- 2.0.0 — 2019-02-19
- 1.2.0 — 2019-02-13
- 1.1.6 — 2019-02-12
- … 7 more at https://npm.io/package/phtml/versions

## README

# phtml [<img src="https://phtml.io/logo.svg" alt="phtml" width="90" height="90" align="right">][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],
[<abbr title="Eleventy"></abbr>][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 "<h1 md>phtml **Markdown**</h1>" | npx phtml -p @phtml/markdown

# <h1>phtml <strong>Markdown</strong></h1>
```

### Node

Add [phtml] to your build tool:

```bash
npm install phtml --save-dev
```

Use [phtml] to process your CSS:

```js
const phtml = require('phtml');

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

#### Node Example

```js
const phtml = require('phtml');

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

/* 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
<script src="https://unpkg.com/phtml"></script>
<script>
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);
</script>
```

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

---
_Source: https://npm.io/package/phtml · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._