Skip to content

Commit 0b36911

Browse files
michael-ciniawskymichael-ciniawsky
committed
docs(README): v1.0.0
1 parent d7d1e85 commit 0b36911

File tree

2 files changed

+179
-96
lines changed

2 files changed

+179
-96
lines changed

‎.travis.yml

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,6 @@ node_js:
55
- 6
66
- 4
77

8-
cache:
9-
directories:
10-
- node_modules
11-
128
after_success:
139
- cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js"
1410

‎README.md

Lines changed: 179 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,244 @@
1-
[![NPM][npm]][npm-url]
2-
[![Deps][deps]][deps-url]
3-
[![Tests][build]][build-url]
4-
[![Coverage][cover]][cover-url]
5-
[![Standard Code Style][style]][style-url]
6-
[![Chat][chat]][chat-badge]
1+
[![npm][npm]][npm-url]
2+
[![node][node]][node-url]
3+
[![deps][deps]][deps-url]
4+
[![tests][tests]][tests-url]
5+
[![coverage][cover]][cover-url]
6+
[![code style][style]][style-url]
7+
[![chat][chat]][chat-url]
8+
9+
<div align="center">
10+
<a href="https://github.com/posthtml/posthtml">
11+
<img width="220" height="200" title="PosHTML" src="http://posthtml.github.io/posthtml/logo.svg">
12+
</a>
13+
<img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
14+
<h1>PostHTML Loader</h1>
15+
</div>
16+
17+
<h2 align="center">Install</h2>
18+
19+
```bash
20+
npm i -D posthtml-loader
21+
```
722

8-
# PostHTML Loader <img align="right" width="200" height="220" title="PostHTML logo" src="http://posthtml.github.io/posthtml/logo.svg">
23+
<h2 align="center">Usage</h2>
924

10-
## Install
25+
```js
26+
import html from './file.html'
27+
```
1128

12-
```sh
13-
npm i -D html-loader posthtml-loader
29+
**webpack.config.js**
30+
```js
31+
module: {
32+
rules: [
33+
{
34+
test: /\.html$/,
35+
use: [
36+
'html-loader',
37+
{
38+
loader: 'posthtml-loader',
39+
options: {
40+
ident: 'posthtml',
41+
parser: 'PostHTML Parser'
42+
plugins: [
43+
/* PostHTML Plugins */
44+
require('posthtml-plugin')(options)
45+
]
46+
}
47+
}
48+
]
49+
}
50+
]
51+
},
1452
```
1553

16-
## Usage
54+
<h2 align="center">Options</h2>
1755

18-
The posthtml loader must be used with at least one other loader in order to integrate with webpack correctly. For most use cases, the [html-loader](https://github.com/webpack/html-loader) is recommended. If you want to export the html string directly for use in javascript or webpack plugins, we recommend the [source-loader](https://github.com/static-dev/source-loader). Whichever loader you choose, it should be the first loader, followed by posthtml, as you will see in the examples below.
56+
|Name|Type|Default|Description|
57+
|:--:|:--:|:-----:|:----------|
58+
|**[`config`](#config)**|`{Object}`|`undefined`|PostHTML Config|
59+
|**[`parser`](#parser)**|`{String/Function}`|`undefined`|PostHTML Parser|
60+
|**[`plugins`](#plugins)**|`{Array/Function}`|`[]`|PostHTML Plugins|
1961

20-
Options can be passed through a `posthtml` option directly on the webpack config object. It accepts an array, an object, or a function that returns an array or object. If it's an array, it should contain plugins. If it's an object, it can contain a `plugins` key, which is an array of plugins and an optional `parser` key which allows you to pass in a custom parser. Any other key will apply to the `pack` querystring parameter, documented below.
62+
### `Config`
2163

22-
Basic configuration example:
64+
|Name|Type|Default|Description|
65+
|:--:|:--:|:-----:|:----------|
66+
|**[`path`](#path)**|`{String}`|`loader.resourcePath`|PostHTML Config Path|
67+
|**[`ctx`](#context)**|`{Object}`|`{}`|PostHTML Config Context|
2368

24-
```js
25-
// webpack.config.js
26-
module: {
27-
loaders: [{
28-
test: /\.html$/,
29-
loader: 'html!posthtml'
30-
}]
31-
},
32-
posthtml: [/* plugins here */]
33-
```
69+
If you want to use are shareable config file instead of inline options in your `webpack.config.js` create a `posthtml.config.js` file and placed it somewhere down the file tree in your project. The nearest config relative to `dirname(file)` currently processed by the loader applies. This enables **Config Cascading**. Despite some edge cases the config file will be loaded automatically and **no** additional setup is required. If you don't intend to use Config Cascading, it's recommended to place `posthtml.config.js` in the **root** `./` of your project
3470

35-
## Options
71+
```
72+
|– src
73+
||– components
74+
|||– component.html
75+
|||– posthtml.config.js (components)
76+
||– index.html
77+
|
78+
|– posthtml.config.js (index)
79+
|– webpack.config.js
80+
```
3681

37-
### Plugin Packages
82+
#### `Path`
3883

39-
If you need to apply different sets of plugins to different groups of files, you can use a **plugin pack**. Just add `pack=[name]` as a querystring option, and return an object from the `posthtml` config option with a key matching the pack name, and the value being an array of plugins.
84+
If you normally place all your config files in a separate folder e.g `./config` it is necessary to explicitly set the config path in `webpack.config.js`
4085

86+
**webpack.config.js**
4187
```js
42-
// webpack.config.js
43-
module: {
44-
loaders: [{
45-
test: /\\.special\.html$/,
46-
loader: 'html!posthtml?pack=special'
47-
}]
48-
},
49-
posthtml: {
50-
plugins: [/* plugins that apply anything that's not using a pack */],
51-
special: [ /* plugins specific to the "special" pack */ ],
88+
{
89+
loader: 'posthtml-loader',
90+
options: {
91+
config: {
92+
path: 'path/to/.config/'
93+
}
94+
}
5295
}
5396
```
5497

55-
### Custom Parser
98+
#### `Context`
5699

57-
If you want to use a custom parser, you can pass it in under the `parser` key or as query string in the loader. Below is an example with the [sugarml parser](https://github.com/posthtml/sugarml):
100+
|Name|Type|Default|Description|
101+
|:--:|:--:|:-----:|:----------|
102+
|`env`|`{String}`|`'development'`|process.env.NODE_ENV|
103+
|`file`|`{Object}`|`{ dirname, basename, extname }`|File|
104+
|`options`|`{Object}`|`{}`|Plugin Options (Context)|
58105

106+
[**posthtml.config.js**](https://github.com/posthtml/posthtml-load-config)
59107
```js
60-
// webpack.config.js
61-
const sugarml = require('sugarml')
108+
module.exports = ({ file, options, env }) => ({
109+
parser: 'posthtml-sugarml'
110+
plugins: {
111+
'posthtml-include': options.include
112+
'posthtml-content': options.content
113+
'htmlnano': env === 'production' ? {} : false
114+
}
115+
})
116+
```
62117

63-
module: {
64-
loaders: [{
65-
test: /\\.special\.html$/,
66-
loader: 'html!posthtml'
67-
}]
68-
},
69-
posthtml: {
70-
plugins: [/* posthtml plugins */],
71-
parser: sugarml
118+
**webpack.config.js**
119+
```js
120+
{
121+
loader: 'posthtml-loader',
122+
options: {
123+
config: {
124+
ctx: {
125+
include: {...options}
126+
content: {...options}
127+
}
128+
}
129+
}
72130
}
73131
```
74132

133+
### `Parser`
134+
135+
If you want to use a custom parser e.g [SugarML](https://github.com/posthtml/sugarml), you can pass it in under the `parser` key in the loader options
136+
137+
#### `{String}`
138+
139+
**webpack.config.js**
75140
```js
76-
// webpack.config.js
77-
const sugarml = require('sugarml')
141+
{
142+
loader: 'posthtml-loader',
143+
options: {
144+
parser: 'posthtml-sugarml'
145+
}
146+
}
147+
```
78148

79-
module: {
80-
loaders: [{
81-
test: /\\.special\.html$/,
82-
loader: 'html!posthtml?parser=sugarml'
83-
}]
84-
},
85-
posthtml: {
86-
plugins: [/* posthtml plugins */]
149+
#### `{Function}`
150+
151+
**webpack.config.js**
152+
```js
153+
{
154+
loader: 'posthtml-loader',
155+
options: {
156+
parser: require('posthtml-sugarml')()
157+
}
87158
}
88159
```
89160

90-
### Using a Function
161+
### `Plugins`
162+
163+
Plugins are specified under the `plugins` key in the loader options
91164

92-
You can also return a function from the `posthtml` config value, if you need to for any reason. The function passes along the [loader context](https://webpack.github.io/docs/loaders.html#loader-context) as an argument, so you can get information about the file currently being processed from this and pass it to plugins if needed. For example:
165+
#### `{Array}`
93166

167+
**webpack.config.js**
94168
```js
95-
// webpack.config.js
96-
module: {
97-
loaders: [{
98-
test: /\.html$/,
99-
loader: 'html!posthtml'
100-
}]
101-
},
102-
posthtml: (ctx) => {
103-
return [ plugin({ filename: ctx.resourcePath })]
169+
{
170+
loader: 'posthtml-loader',
171+
options: {
172+
plugins: [
173+
require('posthtml-plugin')()
174+
]
175+
}
104176
}
105177
```
106178

107-
## Maintainers
179+
#### `{Function}`
180+
181+
**webpack.config.js**
182+
```js
183+
{
184+
loader: 'posthtml-loader',
185+
options: {
186+
plugins (loader) {
187+
return [
188+
require('posthtml-plugin')()
189+
]
190+
}
191+
}
192+
}
193+
```
194+
195+
<h2 align="center">Maintainer</h2>
108196

109197
<table>
110198
<tbody>
111199
<tr>
112200
<td align="center">
113201
<img width="150 height="150"
114-
src="https://avatars.githubusercontent.com/u/5419992?v=3&s=150">
202+
src="https://github.com/michael-ciniawsky.png?v=3&s=150">
115203
<br />
116204
<a href="https://github.com/michael-ciniawsky">Michael Ciniawsky</a>
117205
</td>
206+
</tr>
207+
<tbody>
208+
</table>
209+
210+
<h2 align="center">Contributors</h2>
211+
212+
<table>
213+
<tbody>
214+
<tr>
118215
<td align="center">
119-
<img width="150 height="150"
120-
src="https://avatars.githubusercontent.com/u/556932?v=3&s=150">
121-
<br />
122-
<a href="https://github.com/jescalan">Jeff Escalante</a>
123-
</td>
124-
<td align="center">
125-
<img width="150" height="150" src="https://avatars.githubusercontent.com/u/2789192?v=3&s=150">
216+
<img width="150" height="150" src="https://github.com/Gitscrum.png?v=3&s=150">
126217
<br />
127218
<a href="https://github.com/Gitscrum">Ivan Demidov</a>
128219
</td>
129220
</tr>
130221
<tbody>
131222
</table>
132223

133-
## Contributing
134-
135-
See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [CONTRIBUTING](CONTRIBUTING.md).
136-
137-
## LICENSE
138-
139-
[MIT](LICENSE)
140224

141225
[npm]: https://img.shields.io/npm/v/posthtml-loader.svg
142226
[npm-url]: https://npmjs.com/package/posthtml-loader
143227

228+
[node]: https://img.shields.io/node/v/posthtml-loader.svg
229+
[node-url]: https://nodejs.org/
230+
144231
[deps]: https://david-dm.org/posthtml/posthtml-loader.svg
145232
[deps-url]: https://david-dm.org/posthtml/posthtml-loader
146233

147-
[build]: http://img.shields.io/travis/posthtml/posthtml-loader.svg
148-
[build-url]: https://travis-ci.org/posthtml/posthtml-loader
234+
[tests]: http://img.shields.io/travis/posthtml/posthtml-loader.svg
235+
[tests-url]: https://travis-ci.org/posthtml/posthtml-loader
149236

150-
[cover]: https://coveralls.io/repos/github/posthtml/posthtml-loader/badge.svg?branch=master
151-
[cover-url]: https://coveralls.io/github/posthtml/posthtml-loader?branch=master
237+
[cover]: https://coveralls.io/repos/github/posthtml/posthtml-loader/badge.svg
238+
[cover-url]: https://coveralls.io/github/posthtml/posthtml-loader
152239

153240
[style]: https://img.shields.io/badge/code%20style-standard-yellow.svg
154241
[style-url]: http://standardjs.com/
155242

156243
[chat]: https://badges.gitter.im/posthtml/posthtml.svg
157-
[chat-badge]: https://gitter.im/posthtml/posthtml?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"
244+
[chat-url]: https://gitter.im/posthtml/posthtml

0 commit comments

Comments
 (0)