Skip to content

Commit 6ccf1ab

Browse files
author
Damir
committed
Readme update
1 parent d5f665e commit 6ccf1ab

File tree

4 files changed

+81
-72
lines changed

4 files changed

+81
-72
lines changed

‎.clintonrc.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
"src/**",
66
"lib/**",
77
".idea/**",
8-
"*.{html,jpg}"
8+
"*.{html,jpg}",
9+
"cache.json"
910
],
1011
"rules": {
1112
"pkg-main": "off",

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ npm-debug.log
55
.idea
66
/.idea/*
77
.DS_Store
8-
.vscode
8+
.vscode
9+
cache.json

‎readme.md

+71-63
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,110 @@
1-
# PLUGIN_NAME <img align="right" height="100" title="PostHTML logo" src="http://posthtml.github.io/posthtml/logo.svg">
1+
<div align="center">
2+
<img width="300" title="PostHTML" src="http://posthtml.github.io/posthtml/logo.svg">
3+
<h1>PostHTML Components </h1>
4+
<p>HTML-friendly syntax component with slots, attributes as locals and more!</p>
5+
</div>
26

3-
[![Actions Status][action]][action-url]
47
[![NPM][npm]][npm-url]
58
[![Coverage][cover]][cover-badge]
69
[![XO code style][style]][style-url]
710

8-
Clone this repo and explain what your plugin do and why thousands of people need it ;)
9-
10-
Before:
11-
``` html
12-
<html>
13-
<body>
14-
<p class="wow">OMG</p>
15-
</body>
16-
</html>
17-
```
18-
19-
After:
20-
``` html
21-
<svg xmlns="http://www.w3.org/2000/svg">
22-
<text class="wow" id="wow_id" fill="#4A83B4" fill-rule="evenodd" font-family="Verdana">
23-
OMG
24-
</text>
25-
</svg>
26-
```
27-
2811
## Install
2912

30-
Describe how big guys can install your plugin.
31-
3213
```bash
33-
npm i PLUGIN_NAME
14+
npm i -D posthtml-components
3415
```
3516

36-
## Usage
17+
## Introduction
3718

38-
Describe how people can use this plugin. Include info about build systems if it's
39-
necessary.
19+
This PostHTML plugin provides an HTML-friendly syntax for write components in your templates.
20+
If you are familiar with Blade, you will find similar syntax as this plugin was inspired by it.
21+
See below a basic example, as code is worth a thousand words.
4022

41-
``` js
42-
const fs = require('fs');
43-
const posthtml = require('posthtml');
44-
const PLUGIN_NAME_CAMEL = require('PLUGIN_NAME');
23+
## Basic example
4524

46-
posthtml()
47-
.use(PLUGIN_NAME_CAMEL({ /* options */ }))
48-
.process(html/*, options */)
49-
.then(result => fs.writeFileSync('./after.html', result.html));
50-
```
25+
Create the component:
5126

52-
## Options
53-
54-
Describe all features of your plugin with examples of usage.
27+
``` html
28+
<!-- src/button.html -->
29+
<button class="btn btn-primary">
30+
<slot></slot>
31+
</button>
32+
```
5533

56-
### Feature
34+
Use the component:
5735

58-
Before:
5936
``` html
37+
<!-- src/index.html -->
6038
<html>
61-
<body>
62-
<p>OMG</p>
63-
</body>
39+
<body>
40+
<x-button>Submit</x-button>
41+
</body>
6442
</html>
6543
```
6644

67-
Add option:
68-
``` js
69-
const fs = require('fs');
70-
const posthtml = require('posthtml');
71-
const PLUGIN_NAME_CAMEL = require('PLUGIN_NAME');
45+
Init PostHTML:
46+
47+
```js
48+
<!-- index.js -->
49+
const { readFileSync, writeFileSync } = require('fs')
7250

73-
posthtml()
74-
.use(PLUGIN_NAME_CAMEL({ feature: 'wow' }))
75-
.process(html/*, options */)
76-
.then(result => fs.writeFileSync('./after.html', result.html));
51+
const posthtml = require('posthtml')
52+
const components = require('posthtml-components')
53+
54+
posthtml(components({ root: './src' }))
55+
.process(readFileSync('src/index.html', 'utf8'))
56+
.then((result) => writeFileSync('dist/index.html', result.html, 'utf8'))
7757
```
7858

79-
After:
59+
Result:
60+
8061
``` html
62+
<!-- dist/index.html -->
8163
<html>
82-
<body>
83-
<p class="wow">OMG</p>
84-
</body>
64+
<body>
65+
<button class="btn btn-primary">Submit</button>
66+
</body>
8567
</html>
8668
```
8769

88-
### Contributing
70+
## Options
8971

90-
See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](CONTRIBUTING.md).
72+
| Option | Default | Description |
73+
|:------------------------:|:---------------------------------:|:------------------------------------------------------------------------------------------------------------|
74+
| **root** | `'./'` | String value as root path for components lookup. |
75+
| **roots** | `''` | Array of additional multi roots path from `options.root`. |
76+
| **namespaces** | `[]` | Array of namespace's root path, fallback path and custom path for override. |
77+
| **namespaceSeparator** | `::` | String value for namespace separator to be used with tag name. Example `<x-namespace::button>` |
78+
| **namespaceFallback** | `false` | Boolean value for use fallback path to defined roots in `options.roots`. |
79+
| **fileExtension** | `html` | String value for file extension of the components used for retrieve x-tag file. |
80+
| **tagPrefix** | `x-` | String for tag prefix. |
81+
| **tagRegExp** | `new RegExp('^x-'), 'i')` | Object for regex used to match x-tag. Set only `options.tagPrefix` to keep default. |
82+
| **slotTagName** | `slot` | String value for slot tag name. |
83+
| **fallbackSlotTagName** | `false` | Boolean value used to support posthtml-modules slot `<content>`. |
84+
| **tagName** | `component` | String value for component tag. |
85+
| **tagNames** | `[]` | Array of additional component tag. Useful if you are migrating from extend and modules. |
86+
| **attribute** | `src` | String value for component attribute for set path. |
87+
| **attributes** | `[]` | Array of additional component path to be used for migrating from extend and modules. |
88+
| **expressions** | `{}` | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example. |
89+
| **plugins** | `[]` | PostHTML plugins to apply for every parsed components. |
90+
| **encoding** | `utf8` | String value for the encoding of the component. |
91+
| **scriptLocalAttribute** | `defaultLocals` | String value for set custom attribute parsed by the plugin to retrieve default locals in the components. |
92+
| **matcher** | `[]` | Array of object used to match the tags. Useful if you are migrating from extend and modules. |
93+
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
94+
95+
## Feature
96+
97+
TODO...
98+
99+
## Contributing
91100

92-
[action]: https://github.com/USER_NAME/PLUGIN_NAME/workflows/Actions%20Status/badge.svg
93-
[action-url]: https://github.com/USER_NAME/PLUGIN_NAME/actions?query=workflow%3A%22CI+tests%22
101+
See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](CONTRIBUTING.md).
94102

95103
[npm]: https://img.shields.io/npm/v/PLUGIN_NAME.svg
96104
[npm-url]: https://npmjs.com/package/PLUGIN_NAME
97105

98106
[style]: https://img.shields.io/badge/code_style-XO-5ed9c7.svg
99-
[style-url]: https://github.com/xojs/xo
107+
[style-url]: https://github.com/sindresorhus/xo
100108

101109
[cover]: https://coveralls.io/repos/USER_NAME/PLUGIN_NAME/badge.svg?branch=master
102110
[cover-badge]: https://coveralls.io/r/USER_NAME/PLUGIN_NAME?branch=master

‎src/index.js

+6-7
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ function processNodes(tree, options, messages) {
3939
// we want to support multiple attributes for define path
4040
const attributePath = (options.attributes.length > 0 && options.attributes.find(attribute => node.attrs[attribute])) || options.attribute;
4141

42-
const filePath = node.attrs[attributePath] || findPathFromTagName(node, options);
42+
let filePath = node.attrs[attributePath] || findPathFromTagName(node, options);
4343

4444
// Return node as-is when strict mode is disabled
4545
// otherwise raise error happen in find-path.js
@@ -49,9 +49,9 @@ function processNodes(tree, options, messages) {
4949

5050
delete node.attrs[attributePath];
5151

52-
const layoutPath = path.resolve(options.root, filePath);
52+
filePath = path.resolve(options.root, filePath);
5353

54-
const html = parseToPostHtml(fs.readFileSync(layoutPath, options.encoding));
54+
const html = parseToPostHtml(fs.readFileSync(filePath, options.encoding));
5555

5656
const {attributes, defaultLocals} = parseLocals(options, node, html);
5757

@@ -89,7 +89,7 @@ function processNodes(tree, options, messages) {
8989

9090
messages.push({
9191
type: 'dependency',
92-
file: layoutPath,
92+
file: filePath,
9393
from: options.from
9494
});
9595

@@ -326,13 +326,12 @@ module.exports = (options = {}) => {
326326
tagNames: [],
327327
attribute: 'src',
328328
attributes: [],
329-
locals: {},
330329
expressions: {},
331330
plugins: [],
332331
encoding: 'utf8',
333-
strict: true,
334332
scriptLocalAttribute: 'defaultLocals',
335-
matcher: []
333+
matcher: [],
334+
strict: true
336335
},
337336
...options
338337
};

0 commit comments

Comments
 (0)