From fb579e12c934f0c67652630c772b54d466fc38b8 Mon Sep 17 00:00:00 2001 From: Kevin Van Lierde Date: Fri, 4 Feb 2022 18:31:34 +0100 Subject: [PATCH] feat: add Jsdocs, update readme, add badges, add engines.node property --- README.md | 88 +++++++++++++++++++++++++++++++--------------------- index.js | 19 ++++++++++-- package.json | 3 ++ 3 files changed, 72 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 5670e73..e2e9ad0 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,32 @@ # metalsmith-postcss -[![Build Status](https://travis-ci.org/axa-ch/metalsmith-postcss.svg?branch=master)](https://travis-ci.org/axa-ch/metalsmith-postcss) -[![Greenkeeper badge](https://badges.greenkeeper.io/axa-ch/metalsmith-postcss.svg)](https://greenkeeper.io/) -[![Known Vulnerabilities](https://snyk.io/test/github/axa-ch/metalsmith-postcss/badge.svg)](https://snyk.io/test/github/axa-ch/metalsmith-postcss) -[![NSP Status](https://nodesecurity.io/orgs/axa-ch/projects/394d1209-83a5-48f4-ae04-19dde4db3763/badge)](https://nodesecurity.io/orgs/axa-ch/projects/394d1209-83a5-48f4-ae04-19dde4db3763) +A [Metalsmith](http://metalsmith.io/) plugin that sends your CSS through any [PostCSS](https://github.com/postcss/postcss) plugins. -> A Metalsmith plugin that sends your CSS -> through any [PostCSS](https://github.com/postcss/postcss) plugins. +[![metalsmith: plugin][metalsmith-badge]][metalsmith-url] +[![npm: version][npm-badge]][npm-url] +[![ci: build][ci-badge]][ci-url] +[![Known Vulnerabilities](https://snyk.io/test/github/axa-ch/metalsmith-postcss/badge.svg)](https://snyk.io/test/github/axa-ch/metalsmith-postcss) +[![license: MIT][license-badge]][license-url] ## Installation +NPM: ```sh npm install metalsmith-postcss ``` -## Getting Started - -If you haven't checked out [Metalsmith](http://metalsmith.io/) before, -head over to their website and check out the documentation. +Yarn: +```sh +yarn add metalsmith-postcss +``` -## JavaScript API +## Usage -Using the JavaScript api for Metalsmith, -just add the postcss package name, optionally with it’s -options, to your `.use()` directives. Here is an example -using `postcss-pseudoelements` and `postcss-nested` to -transform your source files. +Add the postcss package name, optionally with its options, to your `.use()` directives. +Here is an example using `postcss-pseudoelements` and `postcss-nested` to transform your source files: ```js -var postcss = require('metalsmith-postcss'); +const postcss = require('metalsmith-postcss'); metalsmith.use(postcss({ plugins: { @@ -38,6 +36,12 @@ metalsmith.use(postcss({ })); ``` +### Options + +* **pattern** `{string|string[]}` *(optional)* - Pattern of CSS files to match relative to `Metalsmith.source()`. Defaults to `**/*.css` +* **plugins** `{Object|Array}` *(optional)* - An object with PostCSS plugin names as keys and their options as values, or an array of PostCSS plugins as names, eg `'postcss-plugin'`or objects in the format `{ 'postcss-plugin': {...options}}` +* **map** {boolean|{inline:boolean}}` *(optional)* - Pass `true` for inline sourcemaps, or `{ inline: false }` for external source maps + By default, files with `.css` extension will be parsed. This may be overridden by providing a custom pattern e.g. @@ -48,23 +52,6 @@ metalsmith.use(postcss({ })); ``` -## Metalsmith CLI - -Using the Metalsmith CLI, just add the postcss package name, -optionally with it’s options, to your `metalsmith.json` config. -Here is an example using `postcss-pseudoelements` and `postcss-nested` -to transform your source files. - -```js -"metalsmith-postcss": { - "plugins": { - "postcss-pseudoelements": {}, - "postcss-nested": {} - }, - "map": true -} -``` - ## Alternative plugin definition syntax Sometime in PostCSS, plugins need to be defined in a certain order and JavaScript @@ -92,8 +79,7 @@ can enable them using several ways. ### Inline sourcemaps -Add `map: true` to the `options` argument to get your -sourcemaps written into the source file. +Add `map: true` to the `options` argument to get your sourcemaps written into the source file. ```js metalsmith.use(postcss({ @@ -128,6 +114,21 @@ metalsmith.use(postcss({ })); ``` +## CLI usage + +Using the Metalsmith CLI, just add the postcss package name, optionally with its options, to your `metalsmith.json` config. +Here is an example using `postcss-pseudoelements` and `postcss-nested` to transform your source files. + +```js +"metalsmith-postcss": { + "plugins": { + "postcss-pseudoelements": {}, + "postcss-nested": {} + }, + "map": true +} +``` + ## Test To run the tests use: @@ -135,3 +136,18 @@ To run the tests use: ```sh npm test ``` + +To view end-to-end tests in browser, use: + +```sh +npm run test:e2e +``` + +[npm-badge]: https://img.shields.io/npm/v/metalsmith-postcss.svg +[npm-url]: https://www.npmjs.com/package/metalsmith-postcss +[ci-url]: https://github.com/axa-ch/metalsmith-postcss/actions/workflows/test.yml +[ci-badge]: https://github.com/axa-ch/metalsmith-postcss/actions/workflows/test.yml/badge.svg +[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true +[metalsmith-url]: https://metalsmith.io +[license-badge]: https://img.shields.io/github/license/axa-ch/metalsmith-postcss +[license-url]: LICENSE \ No newline at end of file diff --git a/index.js b/index.js index e4b8004..6fdaeaa 100644 --- a/index.js +++ b/index.js @@ -13,6 +13,21 @@ function normalizeMapOptions(map) { }; } +/** + * @typedef {Object} SourceMapOptions + * @property {boolean} inline + */ + +/** + * A metalsmith plugin that sends your CSS through any [PostCSS](https://github.com/postcss/postcss) plugins + * @param {Object} options + * @param {string|string[]} [options.pattern] Pattern(s) of CSS files to match relative to `Metalsmith.source()`. Default is `**\/*.css` + * @param {boolean|SourceMapOptions} [options.map] Pass `true` for inline sourcemaps, or `{ inline: false }` for external source maps + * @param {string|{'postcss-plugin': Object}|Array<{'postcss-plugin': Object}|string>} options.plugins + * An object with PostCSS plugin names as keys and their options as values, or an array of PostCSS plugins as names, eg `'postcss-plugin'` + * or objects in the format `{ 'postcss-plugin': {...options}}` + * @returns {import('metalsmith').Plugin} + */ function initPostcss(options) { options = options || {}; @@ -39,7 +54,7 @@ function initPostcss(options) { const processor = postcssLib(plugins); return function postcss(files, metalsmith, done) { - const styles = Object.keys(files).filter(minimatch.filter(options.pattern || '*.css', { matchBase: true })); + const styles = Object.keys(files).filter(minimatch.filter(options.pattern || '**/*.css')); if(styles.length == 0) { done(); @@ -88,4 +103,4 @@ function initPostcss(options) { }; } -module.exports = initP; \ No newline at end of file +module.exports = initPostcss; \ No newline at end of file diff --git a/package.json b/package.json index 765d505..957240b 100644 --- a/package.json +++ b/package.json @@ -48,5 +48,8 @@ "peerDependencies": { "metalsmith": "^2.3.0", "postcss": "^5.0.4 || ^6.0.0 || ^7.0.0 || ^8.0.0" + }, + "engines": { + "node": ">=8.17.0" } }