https://github.com/calebdwilliams/postcss-style-docs
https://github.com/calebdwilliams/postcss-style-docs
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/calebdwilliams/postcss-style-docs
- Owner: calebdwilliams
- License: mit
- Created: 2022-05-11T04:18:02.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2022-05-26T15:18:53.000Z (about 4 years ago)
- Last Synced: 2024-10-29T09:51:37.486Z (over 1 year ago)
- Language: TypeScript
- Size: 488 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# postcss-style-docs
[PostCSS] plugin for dynamically adding documentation to styles.
[PostCSS]: https://github.com/postcss/postcss
The `postcss-style-docs` pluin will walk through your input CSS and create a map of styles to documentation blocks as a message output.
```css
/**
* @docs
* This is a documentation block for the .foo class
* it can be multiple lines
*/
.foo {
/* Input example */
}
```
```css
.foo {
/* Output example */
}
```
## Usage
**Step 1:** Install plugin:
```sh
npm install --save-dev postcss postcss-style-docs
```
**Step 2:** The `postcss-style-docs` plugin works best when manually calling `postcss.process` which enables users to get data out of the plugin:
```javascript
import postcss from 'postcss';
import { getDocs, styleDocsPlugin } from './lib/cjs/index';
const inputCSS = `
/**
* @docs
* We're doing something really fancy and our users are going
* to love it.
*/
.something-fancy {
color: tomato;
}
/** @docs Make it pop */
.something-fancy--pop {
background: papayawhip;
}
`;
const { css, messages } = await postcss([
styleDocsPlugin()
]).process(inputCSS, { from: undefined });
const docs = getDocs(messages);
console.log(docs.size); // 2
console.log(docs.get('.something-fancy')); // 'We're doing something really fancy and our users are going to love it'
console.log(docs.get('.something-fancy--pop')); // 'Make it pop'
```
[official docs]: https://github.com/postcss/postcss#usage