Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phtmlorg/phtml
Transform HTML with JavaScript
https://github.com/phtmlorg/phtml
Last synced: about 2 months 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-07-18T08:45:42.642Z (2 months ago)
- Language: JavaScript
- Homepage: https://phtml.io
- Size: 211 KB
- Stars: 69
- 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