A Metalsmith plugin that sends your CSS through any PostCSS plugins.
npm install @metalsmith/postcssA Metalsmith plugin that sends your CSS through any PostCSS plugins.
[![metalsmith: plugin][metalsmith-badge]][metalsmith-url]
[![npm: version][npm-badge]][npm-url]
[![ci: build][ci-badge]][ci-url]
[![code coverage][codecov-badge]][codecov-url]
[![license: MIT][license-badge]][license-url]
NPM:
``sh`
npm install @metalsmith/postcss
Yarn:
`sh`
yarn add @metalsmith/postcss
_Note_: you need to install postcss and postcss plugins separately
Add the postcss package name, optionally with its options, to your .use() directives.postcss-pseudoelements
Here is an example using and postcss-nested to transform your source files:
`js
import postcss from '@metalsmith/postcss';
// defaults with 2 plugins:
metalsmith.use(postcss({ plugins: {
'postcss-pseudoelements': {}
'postcss-nested': {}
}}))
// explicit defaults with 2 plugins:
metalsmith.use(postcss({
pattern: '*/.css',
plugins: {
'postcss-pseudoelements': {}
'postcss-nested': {}
},
map: false
}));
`
- pattern {string|string[]} _(optional)_ - Pattern of CSS files to match relative to Metalsmith.source(). Defaults to */.css
- plugins _(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}}truefor inline sourcemaps, or{ inline: false } for external source maps
- syntax {string} _(optional)_ - Module name of a PostCSS Syntax or a syntax object itself. Can also be a custom syntax or a relative module path.
By default, files with .css extension will be parsed. This may be overridden
by providing a custom pattern e.g.
``js`
metalsmith.use(postcss({
pattern: '*.postcss',
plugins: { ... }
}));
Sometimes plugins need to be defined in a certain order and JavaScript Objects cannot guarantee the order of keys in an object. You can also specify PostCSS plugins using an array of objects:
`js`
metalsmith.use(
postcss({
pattern: '*.postcss',
plugins: ['postcss-pseudoelements', { 'postcss-nested': { some: 'config' } }]
})
)
This plugin supports generating source maps. To do so, pass map: true for inline source maps (written into the CSS file), or map: { inline: false } for external source maps (written as file.css.map):
`js`
metalsmith.use(
postcss({
plugins: {},
map: true // same as { inline: false }
})
)
Example config for external source maps
`js`
metalsmith.use(
postcss({
plugins: {},
map: {
inline: false
}
})
)
Source maps generation is compatible with @metalsmith/sass and will find correct file paths from .scss source all the way through the last PostCSS transforms:
`js`
metalsmith
.use(
sass({
entries: {
'src/index.scss': 'index.css'
}
})
)
.use(
postcss({
map: true
})
)
To use this plugin with the Metalsmith CLI, add @metalsmith/postcss to the plugins key in your metalsmith.json file:postcss-pseudoelements
Here is an example using and postcss-nested to transform your source files.
`json`
{
"plugins": [
{
"@metalsmith/postcss": {
"plugins": {
"postcss-pseudoelements": {},
"postcss-nested": {}
},
"map": true
}
}
]
}
Thanks to AXA Switzerland for developing the initial versions of this plugin on which this plugin is based.
[MIT][license-url]
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/metalsmith/postcss/actions/workflows/test.yml
[ci-badge]: https://github.com/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
[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/postcss
[codecov-url]: https://coveralls.io/github/metalsmith/postcss
[license-badge]: https://img.shields.io/github/license/metalsmith/postcss
[license-url]: LICENSE