diff options
Diffstat (limited to 'node_modules/postcss/docs')
| -rw-r--r-- | node_modules/postcss/docs/guidelines/plugin.md | 195 | ||||
| -rw-r--r-- | node_modules/postcss/docs/guidelines/runner.md | 143 | ||||
| -rw-r--r-- | node_modules/postcss/docs/source-maps.md | 72 | ||||
| -rw-r--r-- | node_modules/postcss/docs/syntax.md | 231 |
4 files changed, 0 insertions, 641 deletions
diff --git a/node_modules/postcss/docs/guidelines/plugin.md b/node_modules/postcss/docs/guidelines/plugin.md deleted file mode 100644 index 4814b0fa..00000000 --- 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 83f20873..00000000 --- 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. diff --git a/node_modules/postcss/docs/source-maps.md b/node_modules/postcss/docs/source-maps.md deleted file mode 100644 index 6b8e56bb..00000000 --- a/node_modules/postcss/docs/source-maps.md +++ /dev/null @@ -1,72 +0,0 @@ -# PostCSS and Source Maps - -PostCSS has great [source maps] support. It can read and interpret maps -from previous transformation steps, autodetect the format that you expect, -and output both external and inline maps. - -To ensure that you generate an accurate source map, you must indicate the input -and output CSS file paths — using the options `from` and `to`, respectively. - -To generate a new source map with the default options, simply set `map: true`. -This will generate an inline source map that contains the source content. -If you don’t want the map inlined, you can set `map.inline: false`. - -```js -processor - .process(css, { - from: 'app.sass.css', - to: 'app.css', - map: { inline: false }, - }) - .then(function (result) { - result.map //=> '{ "version":3, - // "file":"app.css", - // "sources":["app.sass"], - // "mappings":"AAAA,KAAI" }' - }); -``` - -If PostCSS finds source maps from a previous transformation, -it will automatically update that source map with the same options. - -## Options - -If you want more control over source map generation, you can define the `map` -option as an object with the following parameters: - -* `inline` boolean: indicates that the source map should be embedded - in the output CSS as a Base64-encoded comment. By default, it is `true`. - But if all previous maps are external, not inline, PostCSS will not embed - the map even if you do not set this option. - - If you have an inline source map, the `result.map` property will be empty, - as the source map will be contained within the text of `result.css`. - -* `prev` string, object, boolean or function: source map content from - a previous processing step (for example, Sass compilation). - PostCSS will try to read the previous source map automatically - (based on comments within the source CSS), but you can use this option - to identify it manually. If desired, you can omit the previous map - with `prev: false`. - -* `sourcesContent` boolean: indicates that PostCSS should set the origin - content (for example, Sass source) of the source map. By default, - it is `true`. But if all previous maps do not contain sources content, - PostCSS will also leave it out even if you do not set this option. - -* `annotation` boolean or string: indicates that PostCSS should add annotation - comments to the CSS. By default, PostCSS will always add a comment with a path - to the source map. PostCSS will not add annotations to CSS files that - do not contain any comments. - - By default, PostCSS presumes that you want to save the source map as - `opts.to + '.map'` and will use this path in the annotation comment. - A different path can be set by providing a string value for `annotation`. - - If you have set `inline: true`, annotation cannot be disabled. - -* `from` string: by default, PostCSS will set the `sources` property of the map - to the value of the `from` option. If you want to override this behaviour, you - can use `map.from` to explicitly set the source map's `sources` property. - -[source maps]: http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/ diff --git a/node_modules/postcss/docs/syntax.md b/node_modules/postcss/docs/syntax.md deleted file mode 100644 index 10818f72..00000000 --- a/node_modules/postcss/docs/syntax.md +++ /dev/null @@ -1,231 +0,0 @@ -# How to Write Custom Syntax - -PostCSS can transform styles in any syntax, and is not limited to just CSS. -By writing a custom syntax, you can transform styles in any desired format. - -Writing a custom syntax is much harder than writing a PostCSS plugin, but -it is an awesome adventure. - -There are 3 types of PostCSS syntax packages: - -* **Parser** to parse input string to node’s tree. -* **Stringifier** to generate output string by node’s tree. -* **Syntax** contains both parser and stringifier. - -## Syntax - -A good example of a custom syntax is [SCSS]. Some users may want to transform -SCSS sources with PostCSS plugins, for example if they need to add vendor -prefixes or change the property order. So this syntax should output SCSS from -an SCSS input. - -The syntax API is a very simple plain object, with `parse` & `stringify` -functions: - -```js -module.exports = { - parse: require('./parse'), - stringify: require('./stringify') -}; -``` - -[SCSS]: https://github.com/postcss/postcss-scss - -## Parser - -A good example of a parser is [Safe Parser], which parses malformed/broken CSS. -Because there is no point to generate broken output, this package only provides -a parser. - -The parser API is a function which receives a string & returns a [`Root`] node. -The second argument is a function which receives an object with PostCSS options. - -```js -var postcss = require('postcss'); - -module.exports = function (css, opts) { - var root = postcss.root(); - // Add other nodes to root - return root; -}; -``` - -[Safe Parser]: https://github.com/postcss/postcss-safe-parser -[`Root`]: http://api.postcss.org/Root.html - -### Main Theory - -There are many books about parsers; but do not worry because CSS syntax is -very easy, and so the parser will be much simpler than a programming language -parser. - -The default PostCSS parser contains two steps: - -1. [Tokenizer] which reads input string character by character and builds a - tokens array. For example, it joins space symbols to a `['space', '\n ']` - token, and detects strings to a `['string', '"\"{"']` token. -2. [Parser] which reads the tokens array, creates node instances and - builds a tree. - -[Tokenizer]: https://github.com/postcss/postcss/blob/master/lib/tokenize.es6 -[Parser]: https://github.com/postcss/postcss/blob/master/lib/parser.es6 - -### Performance - -Parsing input is often the most time consuming task in CSS processors. So it -is very important to have a fast parser. - -The main rule of optimization is that there is no performance without a -benchmark. You can look at [PostCSS benchmarks] to build your own. - -Of parsing tasks, the tokenize step will often take the most time, so its -performance should be prioritized. Unfortunately, classes, functions and -high level structures can slow down your tokenizer. Be ready to write dirty -code with repeated statements. This is why it is difficult to extend the -default [PostCSS tokenizer]; copy & paste will be a necessary evil. - -Second optimization is using character codes instead of strings. - -```js -// Slow -string[i] === '{'; - -// Fast -const OPEN_CURLY = 123; // `{' -string.charCodeAt(i) === OPEN_CURLY; -``` - -Third optimization is “fast jumps”. If you find open quotes, you can find -next closing quote much faster by `indexOf`: - -```js -// Simple jump -next = string.indexOf('"', currentPosition + 1); - -// Jump by RegExp -regexp.lastIndex = currentPosion + 1; -regexp.text(string); -next = regexp.lastIndex; -``` - -The parser can be a well written class. There is no need in copy-paste and -hardcore optimization there. You can extend the default [PostCSS parser]. - -[PostCSS benchmarks]: https://github.com/postcss/benchmark -[PostCSS tokenizer]: https://github.com/postcss/postcss/blob/master/lib/tokenize.es6 -[PostCSS parser]: https://github.com/postcss/postcss/blob/master/lib/parser.es6 - -### Node Source - -Every node should have `source` property to generate correct source map. -This property contains `start` and `end` properties with `{ line, column }`, -and `input` property with an [`Input`] instance. - -Your tokenizer should save the original position so that you can propagate -the values to the parser, to ensure that the source map is correctly updated. - -[`Input`]: https://github.com/postcss/postcss/blob/master/lib/input.es6 - -### Raw Values - -A good PostCSS parser should provide all information (including spaces symbols) -to generate byte-to-byte equal output. It is not so difficult, but respectful -for user input and allow integration smoke tests. - -A parser should save all additional symbols to `node.raws` object. -It is an open structure for you, you can add additional keys. -For example, [SCSS parser] saves comment types (`/* */` or `//`) -in `node.raws.inline`. - -The default parser cleans CSS values from comments and spaces. -It saves the original value with comments to `node.raws.value.raw` and uses it, -if the node value was not changed. - -[SCSS parser]: https://github.com/postcss/postcss-scss - -### Tests - -Of course, all parsers in the PostCSS ecosystem must have tests. - -If your parser just extends CSS syntax (like [SCSS] or [Safe Parser]), -you can use the [PostCSS Parser Tests]. It contains unit & integration tests. - -[PostCSS Parser Tests]: https://github.com/postcss/postcss-parser-tests - -## Stringifier - -A style guide generator is a good example of a stringifier. It generates output -HTML which contains CSS components. For this use case, a parser isn't necessary, -so the package should just contain a stringifier. - -The Stringifier API is little bit more complicated, than the parser API. -PostCSS generates a source map, so a stringifier can’t just return a string. -It must link every substring with its source node. - -A Stringifier is a function which receives [`Root`] node and builder callback. -Then it calls builder with every node’s string and node instance. - -```js -module.exports = function (root, builder) { - // Some magic - var string = decl.prop + ':' + decl.value + ';'; - builder(string, decl); - // Some science -}; -``` - -### Main Theory - -PostCSS [default stringifier] is just a class with a method for each node type -and many methods to detect raw properties. - -In most cases it will be enough just to extend this class, -like in [SCSS stringifier]. - -[default stringifier]: https://github.com/postcss/postcss/blob/master/lib/stringifier.es6 -[SCSS stringifier]: https://github.com/postcss/postcss-scss/blob/master/lib/scss-stringifier.es6 - -### Builder Function - -A builder function will be passed to `stringify` function as second argument. -For example, the default PostCSS stringifier class saves it -to `this.builder` property. - -Builder receives output substring and source node to append this substring -to the final output. - -Some nodes contain other nodes in the middle. For example, a rule has a `{` -at the beginning, many declarations inside and a closing `}`. - -For these cases, you should pass a third argument to builder function: -`'start'` or `'end'` string: - -```js -this.builder(rule.selector + '{', rule, 'start'); -// Stringify declarations inside -this.builder('}', rule, 'end'); -``` - -### Raw Values - -A good PostCSS custom syntax saves all symbols and provide byte-to-byte equal -output if there were no changes. - -This is why every node has `node.raws` object to store space symbol, etc. - -Be careful, because sometimes these raw properties will not be present; some -nodes may be built manually, or may lose their indentation when they are moved -to another parent node. - -This is why the default stringifier has a `raw()` method to autodetect raw -properties by other nodes. For example, it will look at other nodes to detect -indent size and them multiply it with the current node depth. - -### Tests - -A stringifier must have tests too. - -You can use unit and integration test cases from [PostCSS Parser Tests]. -Just compare input CSS with CSS after your parser and stringifier. - -[PostCSS Parser Tests]: https://github.com/postcss/postcss-parser-tests |