docs(*): add guidelines and update style

awinogradov · awinogradov · commit d638ce315f66 · 2016-07-23T20:06:00.000+03:00
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,51 @@
+# PostHTML Plugins Guideline
+
+A PostHTML plugin is a function that receives and, usually, transforms a HTML AST from the PostHTML parser. HTML AST has the PostHTML Tree format. [Read more about PostHTML Tree](https://github.com/posthtml/posthtml/blob/master/docs/tree.md).
+
+The rules below are mandatory for all PostHTML plugins.
+
+## Clear name with posthtml- prefix
+
+The plugin’s purpose should be clear just by reading its name. If you wrote a transpiler for HTML  Custom Elements, posthtml-custom-elements would be a good name. If you wrote a plugin to support BEM, posthtml-bem would be a good name.
+
+The prefix posthtml- shows that the plugin is part of the PostHTML ecosystem.
+
+This rule is not mandatory for plugins that can run as independent tools, without the user necessarily knowing that it is powered by PostHTML.
+
+## Do one thing, and do it well
+
+Do not create multitool plugins. Several small, one-purpose plugins bundled into a plugin pack is usually a better solution.
+
+## Plugin must be tested
+
+A CI service like Travis is also recommended for testing code in different environments. You should test in (at least) Node.js 0.12 and stable.
+
+## Use only the public PostHTML API
+
+PostHTML plugins must not rely on undocumented properties or methods, which may be subject to change in any minor release. The public API is described in [API docs](https://github.com/posthtml/posthtml/blob/master/docs/api.md).
+
+## Document your plugin in English
+
+PostHTML plugins must have their README.md written in English. Do not be afraid of your English skills, as the open source community will fix your errors.
+
+Of course, you are welcome to write documentation in other languages; just name them appropriately (e.g. README.ja.md).
+
+## Include input and output examples
+
+The plugin's README.md must contain example input and output HTML. A clear example is the best way to describe how your plugin works.
+
+The first section of the README.md is a good place to put examples. See [posthtml-expressions](https://github.com/posthtml/posthtml-exp) for an example.
+
+Of course, this guideline does not apply if your plugin does not transform the HTML.
+
+## Maintain a changelog
+
+PostHTML plugins must describe the changes of all their releases in a separate file, such as CHANGELOG.md, History.md, or [GitHub Releases](https://help.github.com/articles/creating-releases/). Visit [Keep A Changelog](http://keepachangelog.com/) for more information about how to write one of these.
+
+Of course, you should be using [SemVer](http://semver.org/).
+
+## Include posthtml-plugin keyword in package.json
+
+PostHTML plugins written for npm must have the posthtml-plugin keyword in their package.json. This special keyword will be useful for feedback about the PostHTML ecosystem.
+
+For packages not published to npm, this is not mandatory, but is recommended if the package format can contain keywords.
diff --git a/docs/plugins.md b/docs/plugins.md
@@ -1,10 +1,10 @@
-# PostHTML Plugins
-## Create
-This is a simple function with a single argument.
+# Create PostHTML Plugin
+
+PostHTML plugin is a simple function with a single argument.
 
 > Use [posthtml-plugin-boilerplate][plugin-boilerplate] boilerplate for create new plugin.
 
-### Synchronous plugin example
+## Synchronous plugin example
 
 ```js
 module.exports = function pluginName(tree) {
@@ -20,7 +20,7 @@ module.exports = function pluginName(tree) {
 };
 ```
 
-### Classic asynchronous plugin example
+## Classic asynchronous plugin example
 
 ```js
 var request = request('request');
@@ -51,7 +51,7 @@ module.exports = function pluginName(tree, cb) {
 };
 ```
 
-### Promised asynchronous plugin example
+## Promised asynchronous plugin example
 
 ```js
 import parser from 'posthtml-parser';
@@ -69,4 +69,4 @@ export default tree => {
 };
 ```
 
-[plugin-boilerplate]: https://github.com/jonathantneal/posthtml-plugin-boilerplate
+[plugin-boilerplate]: https://github.com/posthtml/posthtml-plugin-boilerplate
