Skip to content

Commit 5175272

Browse files
cossssmincossssmin
committed
feat: support fileExtension as array
1 parent bcd80ef commit 5175272

6 files changed

Lines changed: 189 additions & 105 deletions

File tree

‎README.md‎

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ Init PostHTML:
5858
```js
5959
// index.js
6060
const posthtml = require('posthtml')
61-
const components = require('posthtml-components')
61+
const components = require('posthtml-component')
6262
const { readFileSync, writeFileSync } = require('node:fs')
6363

6464
posthtml([
@@ -117,47 +117,47 @@ You can clone this repo and run `npm run build` to compile them.
117117

118118
## Options
119119

120-
| Name | Type | Default | Description |
121-
|--------------------------|-------------------|----------------------------------------------|-----------------------------------------------------------------------------------------|
122-
| **root** | `String` | `'./'` | Root path for components lookup. |
123-
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
124-
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
125-
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
126-
| **attribute** | `String` | `'src'` | Component attribute for setting path. |
127-
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
128-
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
129-
| **fileExtension** | `String` | `'html'` | File extension for component files. |
130-
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
131-
| **slot** | `String` | `'slot'` | Tag name for slots. |
132-
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
133-
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
134-
| **push** | `String` | `'push'` | Tag name for `<push>`. |
135-
| **stack** | `String` | `'stack'` | Tag name for `<stack>`. |
136-
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving component props. |
137-
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
138-
| **propsAttribute** | `String` | `'props'` | Attribute to define props as JSON. |
139-
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
140-
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
141-
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
142-
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
143-
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
144-
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
145-
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
146-
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
147-
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
148-
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
149-
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
150-
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |
120+
| Name | Type | Default | Description |
121+
|--------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------|
122+
| **root** | `String` | `'./'` | Root path where to look for components. |
123+
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
124+
| **fileExtension** | `String\|String[]` | `'html'` | Component file extensions to look for. |
125+
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
126+
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
127+
| **attribute** | `String` | `'src'` | Attribute to use for defining path to component file. |
128+
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
129+
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
130+
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
131+
| **slot** | `String` | `'slot'` | Tag name for [slots](#slots) |
132+
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
133+
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
134+
| **stack** | `String` | `'stack'` | Tag name for [`<stack>`](#stacks). |
135+
| **push** | `String` | `'push'` | Tag name for `<push>`. |
136+
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving [component props](#props). |
137+
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
138+
| **propsAttribute** | `String` | `'props'` | Attribute name to define props as JSON on a component tag. |
139+
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
140+
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
141+
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
142+
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
143+
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
144+
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
145+
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
146+
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
147+
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
148+
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
149+
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
150+
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |
151151

152152
## Features
153153

154154
### Tag names and x-tags
155155

156156
You can use the components in multiple ways, or also a combination of them.
157157

158-
If you to use components as 'includes', you may define a tag and src attribute name.
158+
If you want to use components as 'includes', you can define tag and `src` attribute names.
159159

160-
Using our previous button component example, we can define the tag and attribute names and then use it in this way:
160+
Using our previous button component example, we can define the tag and attribute names and then use it like this:
161161

162162
```hbs
163163
<!-- src/index.html -->
@@ -174,7 +174,7 @@ Init PostHTML:
174174
// index.js
175175

176176
require('posthtml')(
177-
require('posthtml-components')({
177+
require('posthtml-component')({
178178
root: './src',
179179
tag: 'component',
180180
attribute: 'src'
@@ -183,16 +183,20 @@ require('posthtml')(
183183
.then(/* ... */)
184184
```
185185

186-
If you need more control over tag matching, you can pass an array of matcher or single object via `options.matcher` like this:
186+
If you need more control over tag matching, you may pass an array of matcher or single object via `options.matcher`:
187187

188188
```js
189189
// index.js
190190
const options = {
191191
root: './src',
192-
matcher: [{tag: 'a-tag'}, {tag: 'another-one'}, {tag: new RegExp(`^app-`, 'i')}]
192+
matcher: [
193+
{tag: 'a-tag'},
194+
{tag: 'another-one'},
195+
{tag: new RegExp(`^app-`, 'i')},
196+
]
193197
};
194198

195-
require('posthtml')(require('posthtml-components')(options))
199+
require('posthtml')(require('posthtml-component')(options))
196200
.process(/* ... */)
197201
.then(/* ... */)
198202
```
@@ -208,7 +212,7 @@ const options = {
208212
tagPrefix: 'x-'
209213
};
210214

211-
require('posthtml')(require('posthtml-components')(options))
215+
require('posthtml')(require('posthtml-component')(options))
212216
.process(/* ... */)
213217
.then(/* ... */)
214218
```
@@ -254,20 +258,21 @@ const options = {
254258
parserOptions: { decodeEntities: true }
255259
};
256260

257-
require('posthtml')(require('posthtml-components')(options))
261+
require('posthtml')(require('posthtml-component')(options))
258262
.process('some HTML', options.parserOptions)
259263
.then(/* ... */)
260264
```
261265

262-
Important: as you can see, whatever `parserOptions` you pass to the plugin, must also be passed in the `process` method in your code, otherwise your PostHTML build will use `posthtml-parser` defaults and will override anything you've passed to `posthtml-component`.
266+
> [!IMPORTANT]
267+
> The `parserOptions` that you pass to the plugin must also be passed in the `process` method in your code, otherwise your PostHTML build will use `posthtml-parser` defaults and will override anything you've passed to `posthtml-component`.
263268
264269
#### Self-closing tags
265270

266271
The plugin supports self-closing tags by default, but you need to make sure to enable them in the `process` method in your code too, by passing `recognizeSelfClosing: true` in the options object:
267272

268273
```js
269274
// index.js
270-
require('posthtml')(require('posthtml-components')({root: './src'}))
275+
require('posthtml')(require('posthtml-component')({root: './src'}))
271276
.process('your HTML...', {recognizeSelfClosing: true})
272277
.then(/* ... */)
273278
```
@@ -287,7 +292,7 @@ const options = {
287292
folders: ['components', 'layouts']
288293
};
289294

290-
require('posthtml')(require('posthtml-components')(options))
295+
require('posthtml')(require('posthtml-component')(options))
291296
.process(/* ... */)
292297
.then(/* ... */)
293298
```
@@ -826,7 +831,7 @@ If default configurations for valid attributes are not right for you, you may co
826831
const { readFileSync, writeFileSync } = require('fs')
827832

828833
const posthtml = require('posthtml')
829-
const components = require('posthtml-components')
834+
const components = require('posthtml-component')
830835

831836
const options = {
832837
root: './src',

0 commit comments

Comments
 (0)