From 6ccf1ab767b3ec7729615b17013a7938573f8c56 Mon Sep 17 00:00:00 2001 From: Damir Date: Thu, 13 Oct 2022 05:45:12 +0200 Subject: [PATCH] Readme update --- .clintonrc.json | 3 +- .gitignore | 3 +- readme.md | 134 +++++++++++++++++++++++++----------------------- src/index.js | 13 +++-- 4 files changed, 81 insertions(+), 72 deletions(-) diff --git a/.clintonrc.json b/.clintonrc.json index 104c5ee..9b6d406 100644 --- a/.clintonrc.json +++ b/.clintonrc.json @@ -5,7 +5,8 @@ "src/**", "lib/**", ".idea/**", - "*.{html,jpg}" + "*.{html,jpg}", + "cache.json" ], "rules": { "pkg-main": "off", diff --git a/.gitignore b/.gitignore index 1bbbff3..6e52888 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ npm-debug.log .idea /.idea/* .DS_Store -.vscode \ No newline at end of file +.vscode +cache.json \ No newline at end of file diff --git a/readme.md b/readme.md index 098a5af..eb725f3 100644 --- a/readme.md +++ b/readme.md @@ -1,102 +1,110 @@ -# PLUGIN_NAME +
+ +

PostHTML Components

+

HTML-friendly syntax component with slots, attributes as locals and more!

+
-[![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 - - -

OMG

- - -``` - -After: -``` html - - - OMG - - -``` - ## 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 + + +``` -### Feature +Use the component: -Before: ``` html + - -

OMG

- + + Submit + ``` -Add option: -``` js -const fs = require('fs'); -const posthtml = require('posthtml'); -const PLUGIN_NAME_CAMEL = require('PLUGIN_NAME'); +Init PostHTML: + +```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 + - -

OMG

- + + + ``` -### 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 `` | +| **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 ``. | +| **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 diff --git a/src/index.js b/src/index.js index d1ce2fd..83e5409 100644 --- a/src/index.js +++ b/src/index.js @@ -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 @@ -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); @@ -89,7 +89,7 @@ function processNodes(tree, options, messages) { messages.push({ type: 'dependency', - file: layoutPath, + file: filePath, from: options.from }); @@ -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 };