diff options
Diffstat (limited to 'node_modules/postcss/docs/guidelines')
| -rw-r--r-- | node_modules/postcss/docs/guidelines/plugin.md | 195 | ||||
| -rw-r--r-- | node_modules/postcss/docs/guidelines/runner.md | 143 |
2 files changed, 0 insertions, 338 deletions
diff --git a/node_modules/postcss/docs/guidelines/plugin.md b/node_modules/postcss/docs/guidelines/plugin.md deleted file mode 100644 index 4814b0f..0000000 --- a/node_modules/postcss/docs/guidelines/plugin.md +++ /dev/null @@ -1,195 +0,0 @@ -# PostCSS Plugin Guidelines - -A PostCSS plugin is a function that receives and, usually, -transforms a CSS AST from the PostCSS parser. - -The rules below are *mandatory* for all PostCSS plugins. - -See also [ClojureWerkz’s recommendations] for open source projects. - -[ClojureWerkz’s recommendations]: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/ - -## 1. API - -### 1.1 Clear name with `postcss-` prefix - -The plugin’s purpose should be clear just by reading its name. -If you wrote a transpiler for CSS 4 Custom Media, `postcss-custom-media` -would be a good name. If you wrote a plugin to support mixins, -`postcss-mixins` would be a good name. - -The prefix `postcss-` shows that the plugin is part of the PostCSS ecosystem. - -This rule is not mandatory for plugins that can run as independent tools, -without the user necessarily knowing that it is powered by -PostCSS — for example, [cssnext] and [Autoprefixer]. - -[Autoprefixer]: https://github.com/postcss/autoprefixer -[cssnext]: http://cssnext.io/ - -### 1.2. 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. - -For example, [cssnext] contains many small plugins, -one for each W3C specification. And [cssnano] contains a separate plugin -for each of its optimization. - -[cssnext]: http://cssnext.io/ -[cssnano]: https://github.com/ben-eb/cssnano - -### 1.3. Do not use mixins - -Preprocessors libraries like Compass provide an API with mixins. - -PostCSS plugins are different. -A plugin cannot be just a set of mixins for [postcss-mixins]. - -To achieve your goal, consider transforming valid CSS -or using custom at-rules and custom properties. - -[postcss-mixins]: https://github.com/postcss/postcss-mixins - -### 1.4. Create plugin by `postcss.plugin` - -By wrapping your function in this method, -you are hooking into a common plugin API: - -```js -module.exports = postcss.plugin('plugin-name', function (opts) { - return function (root, result) { - // Plugin code - }; -}); -``` - -## 2. Processing - -### 2.1. 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 [active LTS](https://github.com/nodejs/LTS) and current stable version. - -[Travis]: https://travis-ci.org/ - -### 2.2. Use asynchronous methods whenever possible - -For example, use `fs.writeFile` instead of `fs.writeFileSync`: - -```js -postcss.plugin('plugin-sprite', function (opts) { - return function (root, result) { - - return new Promise(function (resolve, reject) { - var sprite = makeSprite(); - fs.writeFile(opts.file, function (err) { - if ( err ) return reject(err); - resolve(); - }) - }); - - }; -}); -``` - -### 2.3. Set `node.source` for new nodes - -Every node must have a relevant `source` so PostCSS can generate -an accurate source map. - -So if you add new declaration based on some existing declaration, you should -clone the existing declaration in order to save that original `source`. - -```js -if ( needPrefix(decl.prop) ) { - decl.cloneBefore({ prop: '-webkit-' + decl.prop }); -} -``` - -You can also set `source` directly, copying from some existing node: - -```js -if ( decl.prop === 'animation' ) { - var keyframe = createAnimationByName(decl.value); - keyframes.source = decl.source; - decl.root().append(keyframes); -} -``` - -### 2.4. Use only the public PostCSS API - -PostCSS 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]. - -[API docs]: http://api.postcss.org/ - -## 3. Errors - -### 3.1. Use `node.error` on CSS relevant errors - -If you have an error because of input CSS (like an unknown name -in a mixin plugin) you should use `node.error` to create an error -that includes source position: - -```js -if ( typeof mixins[name] === 'undefined' ) { - throw decl.error('Unknown mixin ' + name, { plugin: 'postcss-mixins' }); -} -``` - -### 3.2. Use `result.warn` for warnings - -Do not print warnings with `console.log` or `console.warn`, -because some PostCSS runner may not allow console output. - -```js -if ( outdated(decl.prop) ) { - result.warn(decl.prop + ' is outdated', { node: decl }); -} -``` - -If CSS input is a source of the warning, the plugin must set the `node` option. - -## 4. Documentation - -### 4.1. Document your plugin in English - -PostCSS 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`). - -### 4.2. Include input and output examples - -The plugin's `README.md` must contain example input and output CSS. -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 [postcss-opacity](https://github.com/iamvdo/postcss-opacity) for an example. - -Of course, this guideline does not apply if your plugin does not -transform the CSS. - -### 4.3. Maintain a changelog - -PostCSS plugins must describe the changes of all their releases -in a separate file, such as `CHANGELOG.md`, `History.md`, or [GitHub Releases]. -Visit [Keep A Changelog] for more information about how to write one of these. - -Of course, you should be using [SemVer]. - -[Keep A Changelog]: http://keepachangelog.com/ -[GitHub Releases]: https://help.github.com/articles/creating-releases/ -[SemVer]: http://semver.org/ - -### 4.4. Include `postcss-plugin` keyword in `package.json` - -PostCSS plugins written for npm must have the `postcss-plugin` keyword -in their `package.json`. This special keyword will be useful for feedback about -the PostCSS ecosystem. - -For packages not published to npm, this is not mandatory, but is recommended -if the package format can contain keywords. diff --git a/node_modules/postcss/docs/guidelines/runner.md b/node_modules/postcss/docs/guidelines/runner.md deleted file mode 100644 index 83f2087..0000000 --- a/node_modules/postcss/docs/guidelines/runner.md +++ /dev/null @@ -1,143 +0,0 @@ -# PostCSS Runner Guidelines - -A PostCSS runner is a tool that processes CSS through a user-defined list -of plugins; for example, [`postcss-cli`] or [`gulp‑postcss`]. -These rules are mandatory for any such runners. - -For single-plugin tools, like [`gulp-autoprefixer`], -these rules are not mandatory but are highly recommended. - -See also [ClojureWerkz’s recommendations] for open source projects. - -[ClojureWerkz’s recommendations]: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/ -[`gulp-autoprefixer`]: https://github.com/sindresorhus/gulp-autoprefixer -[`gulp‑postcss`]: https://github.com/w0rm/gulp-postcss -[`postcss-cli`]: https://github.com/postcss/postcss-cli - -## 1. API - -### 1.1. Accept functions in plugin parameters - -If your runner uses a config file, it must be written in JavaScript, so that -it can support plugins which accept a function, such as [`postcss-assets`]: - -```js -module.exports = [ - require('postcss-assets')({ - cachebuster: function (file) { - return fs.statSync(file).mtime.getTime().toString(16); - } - }) -]; -``` - -[`postcss-assets`]: https://github.com/borodean/postcss-assets - -## 2. Processing - -### 2.1. Set `from` and `to` processing options - -To ensure that PostCSS generates source maps and displays better syntax errors, -runners must specify the `from` and `to` options. If your runner does not handle -writing to disk (for example, a gulp transform), you should set both options -to point to the same file: - -```js -processor.process({ from: file.path, to: file.path }); -``` - -### 2.2. Use only the asynchronous API - -PostCSS runners must use only the asynchronous API. -The synchronous API is provided only for debugging, is slower, -and can’t work with asynchronous plugins. - -```js -processor.process(opts).then(function (result) { - // processing is finished -}); -``` - -### 2.3. Use only the public PostCSS API - -PostCSS runners 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]. - -[API docs]: http://api.postcss.org/ - -## 3. Output - -### 3.1. Don’t show JS stack for `CssSyntaxError` - -PostCSS runners must not show a stack trace for CSS syntax errors, -as the runner can be used by developers who are not familiar with JavaScript. -Instead, handle such errors gracefully: - -```js -processor.process(opts).catch(function (error) { - if ( error.name === 'CssSyntaxError' ) { - process.stderr.write(error.message + error.showSourceCode()); - } else { - throw error; - } -}); -``` - -### 3.2. Display `result.warnings()` - -PostCSS runners must output warnings from `result.warnings()`: - -```js -result.warnings().forEach(function (warn) { - process.stderr.write(warn.toString()); -}); -``` - -See also [postcss-log-warnings] and [postcss-messages] plugins. - -[postcss-log-warnings]: https://github.com/davidtheclark/postcss-log-warnings -[postcss-messages]: https://github.com/postcss/postcss-messages - -### 3.3. Allow the user to write source maps to different files - -PostCSS by default will inline source maps in the generated file; however, -PostCSS runners must provide an option to save the source map in a different -file: - -```js -if ( result.map ) { - fs.writeFile(opts.to + '.map', result.map.toString()); -} -``` - -## 4. Documentation - -### 4.1. Document your runner in English - -PostCSS runners 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`). - -### 4.2. Maintain a changelog - -PostCSS runners must describe changes of all releases in a separate file, -such as `ChangeLog.md`, `History.md`, or with [GitHub Releases]. -Visit [Keep A Changelog] for more information on how to write one of these. - -Of course you should use [SemVer]. - -[Keep A Changelog]: http://keepachangelog.com/ -[GitHub Releases]: https://help.github.com/articles/creating-releases/ -[SemVer]: http://semver.org/ - -### 4.3. `postcss-runner` keyword in `package.json` - -PostCSS runners written for npm must have the `postcss-runner` keyword -in their `package.json`. This special keyword will be useful for feedback about -the PostCSS ecosystem. - -For packages not published to npm, this is not mandatory, but recommended -if the package format is allowed to contain keywords. |