1 | # phtml [<img src="https://phtml.io/logo.svg" alt="phtml" width="90" height="90" align="right">][phtml]
|
2 |
|
3 | [![NPM Version][npm-img]][npm-url]
|
4 | [![Build Status][cli-img]][cli-url]
|
5 | [![Support Chat][git-img]][git-url]
|
6 |
|
7 | [phtml] is a tool for transforming HTML with JavaScript.
|
8 |
|
9 | It fully embraces the HTML language, and aims to help you write and maintain
|
10 | HTML that you _and future you_ feel good about.
|
11 |
|
12 | phtml helps you compose [reusable templates and components](https://github.com/phtmlorg/phtml-template),
|
13 | or automate [image size attributes](https://github.com/phtmlorg/phtml-image-size)
|
14 | and [schema.org microdata](https://github.com/phtmlorg/phtml-schema) and [heading levels](https://github.com/phtmlorg/phtml-h-element),
|
15 | or transform modern [CSS with PostCSS](https://github.com/phtmlorg/phtml-css)
|
16 | and [JS with Babel](https://github.com/phtmlorg/phtml-js).
|
17 |
|
18 | It works in the command line and Node, but also [Grunt], [Gulp],
|
19 | [<abbr title="Eleventy"></abbr>][11ty], [Webpack], [Rollup], and even
|
20 | [the browser itself][browser].
|
21 |
|
22 | ## Usage
|
23 |
|
24 | Transform HTML files directly from the command line:
|
25 |
|
26 | ```bash
|
27 | npx phtml source.html output.html
|
28 | ```
|
29 |
|
30 | Include plugins directly from the command line:
|
31 |
|
32 | ```bash
|
33 | npx phtml source.html output.html -p @phtml/markdown,@phtml/image-alt
|
34 | ```
|
35 |
|
36 | Transform strings from the command line:
|
37 |
|
38 | ```bash
|
39 | echo "<h1 md>phtml **Markdown**</h1>" | npx phtml -p @phtml/markdown
|
40 |
|
41 | # <h1>phtml <strong>Markdown</strong></h1>
|
42 | ```
|
43 |
|
44 | ### Node
|
45 |
|
46 | Add [phtml] to your build tool:
|
47 |
|
48 | ```bash
|
49 | npm install phtml --save-dev
|
50 | ```
|
51 |
|
52 | Use [phtml] to process your CSS:
|
53 |
|
54 | ```js
|
55 | const phtml = require('phtml');
|
56 |
|
57 | phtml.process(YOUR_HTML, /* processOptions */, /* pluginOrPlugins */);
|
58 | ```
|
59 |
|
60 | #### Node Example
|
61 |
|
62 | ```js
|
63 | const phtml = require('phtml');
|
64 |
|
65 | const html = `<my-component class="main">
|
66 | <title>Super Title</title>
|
67 | <text>Awesome Text</text>
|
68 | </my-component>`;
|
69 |
|
70 | phtml.process(html, { from: 'my-component.html' }).then(console.log);
|
71 |
|
72 | /* Result {
|
73 | from: 'component.html',
|
74 | to: 'component.html',
|
75 | root: Fragment {
|
76 | name: '#document-fragment',
|
77 | nodes: NodeList [
|
78 | Element {
|
79 | name: "my-component",
|
80 | attrs: AttributeList [
|
81 | { name: "class", value: "main" }
|
82 | ],
|
83 | nodes: NodeList [
|
84 | Text "\n ",
|
85 | Element {
|
86 | name: "title",
|
87 | nodes: NodeList [
|
88 | Text "Super Title"
|
89 | ]
|
90 | },
|
91 | Text "\n ",
|
92 | Element {
|
93 | name: "text",
|
94 | nodes: NodeList [
|
95 | Text "Awesome Text"
|
96 | ]
|
97 | },
|
98 | Text "\n"
|
99 | ]
|
100 | }
|
101 | ]
|
102 | }
|
103 | }
|
104 | ```
|
105 |
|
106 | #### Using Plugins in Node
|
107 |
|
108 | Add a [phtml] Plugin to your build tool:
|
109 |
|
110 | ```bash
|
111 | npm install phtml-some-thing --save-dev
|
112 | ```
|
113 |
|
114 | ```js
|
115 | const phtml = require('phtml');
|
116 | const postHtmlSomeThing = require('phtml-some-thing');
|
117 |
|
118 | phtml.use(
|
119 | postHtmlSomeThing(/* pluginOptions */)
|
120 | ).process(YOUR_HTML);
|
121 | ```
|
122 |
|
123 | ## Plugins
|
124 |
|
125 | You can find phtml plugins on npm.
|
126 |
|
127 | https://www.npmjs.com/search?q=keywords:phtml-plugin
|
128 |
|
129 | ### Plugin Creation
|
130 |
|
131 | Create plugins directly from the command line:
|
132 |
|
133 | ```bash
|
134 | npm init phtml-plugin
|
135 |
|
136 | # Plugin Name: Example (becomes `phtml Hello` / `phtml-hello`)
|
137 | # Keywords: awesome,blossom (added to package.json keywords)
|
138 | ```
|
139 |
|
140 | Once the command finishes, a new plugin is fully scaffolded with bare
|
141 | functionality, documentation, and tests. Within the plugin directory,
|
142 | functionality is added to `src/index.js`.
|
143 |
|
144 | #### Advanced Plugin Creation
|
145 |
|
146 | Create plugins using a new `Plugin` class:
|
147 |
|
148 | ```js
|
149 | import phtml from 'phtml';
|
150 |
|
151 | export default new phtml.Plugin('phtml-hello', pluginOptions => {
|
152 | // initialization logic
|
153 |
|
154 | return {
|
155 | Element(element, result) {
|
156 | // runtime logic, do something with an element
|
157 | },
|
158 | Root(root, result) {
|
159 | // runtime logic, do something with the root
|
160 | }
|
161 | };
|
162 | });
|
163 | ```
|
164 |
|
165 | The runtime plugin can visit nodes as they are entered or exited.
|
166 |
|
167 | ## Browser Usage
|
168 |
|
169 | phtml works in the browser, which may be great for experimentation:
|
170 |
|
171 | ```html
|
172 | <script src="https://unpkg.com/phtml"></script>
|
173 | <script>
|
174 | const html = `<my-component class="main">
|
175 | <title>Super Title</title>
|
176 | <text>Awesome Text</text>
|
177 | </my-component>`;
|
178 |
|
179 | phtml.process(html, { from: 'my-component.html' }).then(console.log);
|
180 | </script>
|
181 | ```
|
182 |
|
183 | Note that the browser version of phtml is 52 kB because it includes its own
|
184 | HTML parser, [parse5].
|
185 |
|
186 | [cli-img]: https://img.shields.io/travis/phtmlorg/phtml.svg
|
187 | [cli-url]: https://travis-ci.org/phtmlorg/phtml
|
188 | [git-img]: https://img.shields.io/badge/support-chat-blue.svg
|
189 | [git-url]: https://gitter.im/postcss/postcss
|
190 | [npm-img]: https://img.shields.io/npm/v/phtml.svg
|
191 | [npm-url]: https://www.npmjs.com/package/phtml
|
192 |
|
193 | [11ty]: https://github.com/phtmlorg/phtml-11ty
|
194 | [browser]: https://unpkg.com/phtml/
|
195 | [Grunt]: https://github.com/phtmlorg/grunt-phtml
|
196 | [Gulp]: https://github.com/phtmlorg/gulp-phtml
|
197 | [parse5]: https://github.com/inikulin/parse5
|
198 | [phtml]: https://github.com/phtmlorg/phtml
|
199 | [Rollup]: https://github.com/phtmlorg/rollup-plugin-phtml
|
200 | [Webpack]: https://github.com/phtmlorg/phtml-loader
|