Skip to content

Commit

Permalink
Readme update
Browse files Browse the repository at this point in the history
  • Loading branch information
Damir committed Oct 13, 2022
1 parent d5f665e commit 6ccf1ab
Show file tree
Hide file tree
Showing 4 changed files with 81 additions and 72 deletions.
3 changes: 2 additions & 1 deletion .clintonrc.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
"src/**",
"lib/**",
".idea/**",
"*.{html,jpg}"
"*.{html,jpg}",
"cache.json"
],
"rules": {
"pkg-main": "off",
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,5 @@ npm-debug.log
.idea
/.idea/*
.DS_Store
.vscode
.vscode
cache.json
134 changes: 71 additions & 63 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,110 @@
# PLUGIN_NAME <img align="right" height="100" title="PostHTML logo" src="http://posthtml.github.io/posthtml/logo.svg">
<div align="center">
<img width="300" title="PostHTML" src="http://posthtml.github.io/posthtml/logo.svg">
<h1>PostHTML Components </h1>
<p>HTML-friendly syntax component with slots, attributes as locals and more!</p>
</div>

[![Actions Status][action]][action-url]
[![NPM][npm]][npm-url]
[![Coverage][cover]][cover-badge]
[![XO code style][style]][style-url]

Clone this repo and explain what your plugin do and why thousands of people need it ;)

Before:
``` html
<html>
<body>
<p class="wow">OMG</p>
</body>
</html>
```

After:
``` html
<svg xmlns="http://www.w3.org/2000/svg">
<text class="wow" id="wow_id" fill="#4A83B4" fill-rule="evenodd" font-family="Verdana">
OMG
</text>
</svg>
```

## Install

Describe how big guys can install your plugin.

```bash
npm i PLUGIN_NAME
npm i -D posthtml-components
```

## Usage
## Introduction

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

``` js
const fs = require('fs');
const posthtml = require('posthtml');
const PLUGIN_NAME_CAMEL = require('PLUGIN_NAME');
## Basic example

posthtml()
.use(PLUGIN_NAME_CAMEL({ /* options */ }))
.process(html/*, options */)
.then(result => fs.writeFileSync('./after.html', result.html));
```
Create the component:

## Options

Describe all features of your plugin with examples of usage.
``` html
<!-- src/button.html -->
<button class="btn btn-primary">
<slot></slot>
</button>
```

### Feature
Use the component:

Before:
``` html
<!-- src/index.html -->
<html>
<body>
<p>OMG</p>
</body>
<body>
<x-button>Submit</x-button>
</body>
</html>
```

Add option:
``` js
const fs = require('fs');
const posthtml = require('posthtml');
const PLUGIN_NAME_CAMEL = require('PLUGIN_NAME');
Init PostHTML:

```js
<!-- index.js -->
const { readFileSync, writeFileSync } = require('fs')

posthtml()
.use(PLUGIN_NAME_CAMEL({ feature: 'wow' }))
.process(html/*, options */)
.then(result => fs.writeFileSync('./after.html', result.html));
const posthtml = require('posthtml')
const components = require('posthtml-components')

posthtml(components({ root: './src' }))
.process(readFileSync('src/index.html', 'utf8'))
.then((result) => writeFileSync('dist/index.html', result.html, 'utf8'))
```

After:
Result:

``` html
<!-- dist/index.html -->
<html>
<body>
<p class="wow">OMG</p>
</body>
<body>
<button class="btn btn-primary">Submit</button>
</body>
</html>
```

### Contributing
## Options

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

## Feature

TODO...

## Contributing

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

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

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

[cover]: https://coveralls.io/repos/USER_NAME/PLUGIN_NAME/badge.svg?branch=master
[cover-badge]: https://coveralls.io/r/USER_NAME/PLUGIN_NAME?branch=master
13 changes: 6 additions & 7 deletions src/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ function processNodes(tree, options, messages) {
// we want to support multiple attributes for define path
const attributePath = (options.attributes.length > 0 && options.attributes.find(attribute => node.attrs[attribute])) || options.attribute;

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

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

delete node.attrs[attributePath];

const layoutPath = path.resolve(options.root, filePath);
filePath = path.resolve(options.root, filePath);

const html = parseToPostHtml(fs.readFileSync(layoutPath, options.encoding));
const html = parseToPostHtml(fs.readFileSync(filePath, options.encoding));

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

Expand Down Expand Up @@ -89,7 +89,7 @@ function processNodes(tree, options, messages) {

messages.push({
type: 'dependency',
file: layoutPath,
file: filePath,
from: options.from
});

Expand Down Expand Up @@ -326,13 +326,12 @@ module.exports = (options = {}) => {
tagNames: [],
attribute: 'src',
attributes: [],
locals: {},
expressions: {},
plugins: [],
encoding: 'utf8',
strict: true,
scriptLocalAttribute: 'defaultLocals',
matcher: []
matcher: [],
strict: true
},
...options
};
Expand Down

0 comments on commit 6ccf1ab

Please sign in to comment.