More readme

posthtml · Oct 15, 2022 · 2201df2 · 2201df2
1 parent c78d53b
commit 2201df2
Showing 1 changed file with 160 additions and 2 deletions.
diff --git a/readme.md b/readme.md
@@ -92,9 +92,167 @@ Result:
 |       **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
+## Features
 
-TODO...
+### Tag names and x-tags
+
+You can use the components in multiple ways, or also a combination of them.
+Like with `posthtml-extend` and `posthtml-modules` you can define a tag name or multiples tag name in combination with an attribute name or multiple attributes name for set the path to the components.
+
+For example for the same button component `src/button.html` in the basic example we can define the tag name and attribute name and then use it in this way:
+
+``` html
+<!-- src/index.html -->
+<html>
+<body>
+  <component src="button.html">Submit</component>
+</body>
+</html>
+```
+
+Init PostHTML:
+
+```js
+// index.js
+const { readFileSync, writeFileSync } = require('fs')
+
+const posthtml = require('posthtml')
+const components = require('posthtml-components')
+
+posthtml(components({ root: './src', tagName: 'component', attribute: 'src' }))
+  .process(readFileSync('src/index.html', 'utf8'))
+  .then((result) => writeFileSync('dist/index.html', result.html, 'utf8'))
+```
+
+We can also set multiple tag names by passing an array of component name and an array of attribute name, this is useful if you need to migrate from `posthtml-extend` and `posthtml-modules` where you are using different tag name.
+
+Init PostHTML with multiple tag names and attributes:
+
+``` html
+<!-- src/index.html -->
+<html>
+<body>
+  <extends src="button.html">Submit</extends>
+  <module href="button.html">Submit</module>
+</body>
+</html>
+```
+
+```js
+// index.js
+
+const options = { 
+  root: './src', 
+  tagNames: ['extends', 'module'], 
+  attribute: ['src', 'href']
+};
+
+require('posthtml')(require('posthtml-components')(options))
+  .process(/* ... */)
+  .then(/* ... */)
+```
+
+If you need more control over how to match the tags, you can pass directly an array of matcher or single object via `options.matcher` like shown in below example:
+
+```js
+// index.js
+
+const options = { 
+  root: './src', 
+  matcher: [{tag: 'a-tag'}, {tag: 'another-one'}, {tag: new RegExp(`^app-`, 'i')}] 
+};
+
+require('posthtml')(require('posthtml-components')(options))
+  .process(/* ... */)
+  .then(/* ... */)
+```
+
+With `posthtml-components` you don't need to specify the path name when you are using `x-tag-name` syntax. See below example.
+
+Setup PostHTML:
+
+```js
+// index.js
+
+const options = { 
+  root: './src', 
+  tagPrefix: 'x-'
+};
+
+require('posthtml')(require('posthtml-components')(options))
+  .process(/* ... */)
+  .then(/* ... */)
+```
+
+Use:
+
+``` html
+<!-- src/index.html -->
+<html>
+<body>
+  <x-button>Submit</x-button>
+</body>
+</html>
+```
+
+If your components are in a subfolder then you can use `dot` to access it, example:
+
+``` html
+<!-- Supposing your button component is located in ./src/components/forms/button.html -->
+<x-forms.button>Submit</x-forms.button>
+```
+
+If your components are in a sub-folder with multiple files, then for avoid to type the main file you can use `index.html` without specify it.
+Please see below example to understand better.
+
+``` html
+<!-- Supposing your modal component is located in ./src/components/modals/index.html -->
+<x-modal.index>Submit</x-modal.index>
+
+<!-- You can omit "index" part since the file is named "index.html" -->
+<x-modal>Submit</x-modal>
+```
+
+### Multiple roots
+
+You have full control where to place your components. Once you set the main root path of your components, you can then set multiple roots.
+For example let's suppose your main root is `./src` and then you have several folders where you have your components, for example `./src/components` and `./src/layouts`.
+You can setup the plugin like below:
+
+```js
+// index.js
+
+const options = { 
+  root: './src', 
+  roots: ['components', 'layouts'] 
+};
+
+require('posthtml')(require('posthtml-components')(options))
+  .process(/* ... */)
+  .then(/* ... */)
+```
+
+### Namespaces
+
+With namespaces you can define a top level root path to your components like shown in below example:
+
+``` html
+<!-- src/index.html -->
+<html>
+<body>
+  <x-theme-dark::button>Submit</theme-dark::button>
+  <x-theme-light::button>Submit</theme-light::button>
+</body>
+</html>
+```
+
+### Slots
+
+### Props
+
+### Matcher
+
+## Migration from posthtml-extend and posthtml-modules
 
 ## Contributing