matype / postcss-style-guide Goto Github PK
View Code? Open in Web Editor NEWPostCSS plugin to generate a style guide automatically
License: Other
PostCSS plugin to generate a style guide automatically
License: Other
I'm @import
-ing some libraries such as normalize.css. Is there anyway to prevent them from showing up in the guide?
I would like to use the comments for sassdoc and postcss-style-guide. Really wish to see sassdoc /// comment style.
I can't get options.theme
to work...if I use anything but 'default'
, the gulp task finishes, but the guide is never generated (however in my gulp example, the task does complete).
I also never get the Successfully created style guide!
message.
gulp.task('build:styleguide', function() {
return gulp.src(src)
.pipe(postcss(plugins.concat([
require('postcss-style-guide')({
name: config.pkg.title,
dir: path.join(config.paths.dest, 'style'),
file: 'index.html',
theme: 'forest',
})
])));
});
I'm not sure if I'm messing up or what but I really want to be able to show the CSS before all the postCSS formatting takes place and then include the compiled CSS on the page to show how it looks.
Would adding a option of including a extra CSS file be the correct solution to this problem?
I've made some changes locally that work well enough for my use case.
diff --git a/index.js b/index.js
index dbbe8aa..cbd024e 100644
--- a/index.js
+++ b/index.js
@@ -64,7 +64,8 @@ function generate (maps, css, options) {
css: nano(css),
tmplStyle: nano(options.style),
codeStyle: nano(codeStyle),
- maps: maps
+ maps: maps,
+ extraCSS: options.extraCSS
}
var html = ejs.render(options.template, assign)
diff --git a/template.ejs b/template.ejs
index 653b0a0..4cde434 100644
--- a/template.ejs
+++ b/template.ejs
@@ -4,6 +4,9 @@
<meta charset="UTF-8">
<title><%= projectName %></title>
<link rel="stylesheet" href="./default.css">
+ <% if (extraCSS) { %>
+ <link rel="stylesheet" href="<%= extraCSS %>">
+ <% } %>
<style><%- codeStyle %><%- tmplStyle %><%- css %></style>
</head>
<body>
Then I have two gulp tasks, one that builds the CSS with all the postCSS transformations
gulp.task('css', ['clean:css'], function() {
return gulp.src(paths.css)
.pipe(sourcemaps.init())
.pipe(concat('index.css'))
.pipe(postcss([
require('cssnext')(),
require('postcss-nested')(),
require('autoprefixer-core')(),
require('postcss-import')(),
]))
.pipe(sourcemaps.write('.'))
.pipe(gulp.dest('dist/'))
.pipe(connect.reload());
});
and one for the guide where it passes the built CSS filename in as a option.
gulp.task('guide', function() {
return gulp.src(paths.css)
.pipe(postcss([
require('postcss-style-guide')({
name: 'Bókun', extraCSS: "http://localhost:8001/index.css"
})
]));
});
hi there, I just installed postcss as well as postcss-style-guide via npm.
i used your configuration for gulp and it came back with the reference error fs is not defined
any thoughts on what I might be doing wrong?
When the style guide is installed with npm 3 many of it's supporting packages are pulled out to the root of the node_modules folder. When I attempt to build a style guide I encounter this error
Error: ENOENT: no such file or directory, open '/node_modules/postcss-style-guide/node_modules/highlight.js/styles/github.css'
When I look in my node_modules folder hightlight.js
is in the root of node_modules and not in postcss-style-guide
's node_modules. In fact postcss-style-guide
does not event contain a node_modules folder.
Hi!
with reference to this pull request, I had some time to refine some new features and improvements I've made to the plugin.
I'm not submitting a new pull request since it's a lot of stuff and I'm not sure if it could be interesting or not... Moreover I've refactored the code to ES6 for Node v4+ making the plugin not compatible with older stacks (current tests does pass with minimal changes though).
Here is a summary of the changes I made: https://github.com/dwightjack/postcss-style-guide/blob/develop/PROPOSAL-CHANGELOG.md
Feel free to ping me if something is unclear or you see possible improvements.
i have this config
postcss([
require('postcss-import')(),
require('autoprefixer')({ browsers: ['last 5 versions', '> 5%', 'ie >= 10'] }),
require('postcss-atroot'),
require('postcss-mixins'),
require('postcss-simple-vars'),
require('postcss-custom-properties'),
require('postcss-custom-media'),
require('postcss-nested'),
require('postcss-color-function'),
require('postcss-typescale'),
require('postcss-button'),
styleguide({
project: 'Project name',
dest: 'styleguide/app.html',
showCode: true
}),
require('cssnano')({
discardComments: {
removeAll: true
}
})
])
.process(fs.readFileSync('resources/games/css/app.css', 'utf8'), { from: "resources/games/css/app.css" })
.then(result => purify(content, result.css, options))
trying to get the style for a component
/*
@styleguide
@title Component_Name
*/
works fine
but when i want to output colors, there's no output in the styleguide html file.
/* @start color */
:root {
--red: #e23B00;
--blue: #3f526b;
--black: #000;
--background: #faf8f5;
}
/* @end color */
Hi man!
Another issue here.
I have the following CSS:
/*
@styleguide
# This is a example component
Use the component classes on an `<div>` element.
<div class="component">Component</div>
*/
.component {
background-color: black;
color: white; }
/*
@styleguide
# This is a example component 2
Use the component classes on an `<div>` element.
<div class="component">Component 2</div>
*/
.component-2 {
background-color: white;
color: black; }
/*# sourceMappingURL=sourcemaps/styles.css.map */
and the HTML generated:
<body>
<header class="masthead">
<h1>Lights by TENA Style Guide</h1>
<p class="lead">Site modules</p>
</header>
<div class="section">
<div class="col"><h1 id="this-is-a-example-component">This is a example component</h1>
<p>Use the component classes on an <code><div></code> element.</p>
<div class="component">Component</div></div>
<div class="col"><pre class="code"><code class="lang-css"><span class="hljs-class">.component</span> <span class="hljs-rules">{
<span class="hljs-rule"><span class="hljs-attribute">background-color</span>:<span class="hljs-value"> black</span></span>;
<span class="hljs-rule"><span class="hljs-attribute">color</span>:<span class="hljs-value"> white</span></span>; }</span>
<span class="hljs-class">.component-2</span> <span class="hljs-rules">{
<span class="hljs-rule"><span class="hljs-attribute">background-color</span>:<span class="hljs-value"> white</span></span>;
<span class="hljs-rule"><span class="hljs-attribute">color</span>:<span class="hljs-value"> black</span></span>; }</span></code></pre></div>
</div>
<div class="section">
<div class="col"><h1 id="this-is-a-example-component-2">This is a example component 2</h1>
<p>Use the component classes on an <code><div></code> element.</p>
<div class="component">Component 2</div></div>
<div class="col"><pre class="code"><code class="lang-css"><span class="hljs-class">.component-2</span> <span class="hljs-rules">{
<span class="hljs-rule"><span class="hljs-attribute">background-color</span>:<span class="hljs-value"> white</span></span>;
<span class="hljs-rule"><span class="hljs-attribute">color</span>:<span class="hljs-value"> black</span></span>; }</span></code></pre></div>
</div>
</body>
It add up the different comments inside each other so that the first component style declarations will include the other ones that follow. I will try to have a look at my end and see if I can figure out the problem.
Thanks!
All PostCSS plugins must pass Plugin Guidelines.
postcss.plugin
.To generate one HTML document from some css, is it like this?
var fs = require('fs');
var postcss = require('postcss');
var styleGuide = require('postcss-style-guide');
var css = fs.readFileSync('css/sample.css', 'utf-8');
css += fs.readFileSync('css/sample2.css', 'utf-8');
var options = {
name: 'Project name'
};
var output = postcss()
.use(styleGuide(options))
.process(css)
.css;
Hey Morishita,
Thanks for this plugin, it's awesome!
I'm wondering if you could point me the right direction on something please?
I'm having trouble getting this setup with Gulp, while setting options, still having it work with the stream rather than an already processed file.
This works:
gulp.task('css', function () {
var processedCSS = fs.readFileSync('./dest/style.css', 'utf-8');
var processors = [
lost,
styleGuide
];
return gulp.src('./src/*.css')
.pipe(postcss(processors))
.pipe(gulp.dest('./dest'));
});
But I've only been able to pass options if I read from an already processed file:
gulp.task('css', function () {
var processedCSS = fs.readFileSync('./dest/style.css', 'utf-8');
var processors = [
lost,
styleGuide(processedCSS, {
name: 'Auto Style Guide',
theme: '1column'
})
];
return gulp.src('./src/*.css')
.pipe(postcss(processors))
.pipe(gulp.dest('./dest'));
});
Is there a way I can set options while still having the style guide generated from the stream?
I ask as my final file will be run through cssnano so it won't have any comments in it.
FYI I did a quick test and tried swapping the parameters in your plugin so it's:
module.exports = postcss.plugin('postcss-style-guide', function (options, processedCSS ) {
With the two swapped around I was able to set options without passing a processedCSS argument like this:
gulp.task('css', function () {
var processedCSS = fs.readFileSync('./dest/style.css', 'utf-8');
var processors = [
lost,
styleGuide({
name: 'Auto Style Guide',
theme: '1column'
})
];
return gulp.src('./src/*.css')
.pipe(postcss(processors))
.pipe(gulp.dest('./dest'));
});
Is there a way already in there that I just missed?
Please add grunt task example to Readme
--color-darker: color(red shade(50%);
this is the css config
postcss([
require('postcss-import')(),
require('postcss-mixins')(),
require('postcss-nested')(),
require('postcss-style-guide')({
project: 'My Project',
dest: 'styleguide/app.html',
showCode: true
}),
require('postcss-cssnext')({
features: {
customProperties: {},
applyRule: {},
calc: {},
customMedia: {},
mediaQueriesRange: {},
customSelectors: {},
attributeCaseInsensitive: {},
colorRebeccapurple: {},
colorHwb: {},
colorHsl: {},
colorRgb: {},
colorGray: {},
colorHexAlpha: {},
colorFunction: {},
fontVariant: {},
filter: {},
initial: {},
rem: {},
pseudoElements: {},
pseudoClassMatches: {},
pseudoClassNot: {},
pseudoClassAnyLink: {},
colorRgba: {},
overflowWrap: {},
autoprefixer: false
}
}),
require('postcss-typescale'),
require('postcss-button')
])
.process(fs.readFileSync('resources/games/css/app.css', 'utf8'), { from: "resources/games/css/app.css" })
.then(result => purify(content, result.css, options))
.catch(error => {
console.error(error);
});
Awesome idea! Feel free to send a PR to Plugins section in PostCSS README.md.
Hi!
First I would like to thank for the awesome plugin! But I am having a little bit of trouble trying to make it work here.
I try to run the plugin with the exact same bit of css as in the example you have and a see the "Successfully created style guide!" output on the CMD, the style guide file is generated with the specific title I pass as a parameter to the plugin. The thing is that the page does not render the markdown from my css.
I have a separated folder for my gulp tasks that I then import with babel on the project root folder. I don't know if that might be a problem, but I can't see why it would.
I have the following structure:
app / css / test.css
gulp / tasks / styleguide.js
build/styleguide/index.html
gulpfile.babel.js
test.css contains the following:
/*
@document
# I love Twitter Bootstrap
Use the button classes on an `<a>`, `<button>`, `<input>` element.
<button class="btn">Button</button>
<button class="btn">Button</button>
*/
.btn {
display: inline-block;
padding: 6px 12px;
margin-bottom: 0;
font-size: 14px;
font-weight: normal;
line-height: 1.42857143;
text-align: center;
white-space: nowrap;
vertical-align: middle;
touch-action: manipulation;
cursor: pointer;
user-select: none;
background-image: none;
border: 1px solid transparent;
border-radius: 4px;
}
.btn:hover,
.btn:focus,
.btn.focus {
color: #333;
text-decoration: none;
}
the styleguide task looks like this:
gulp.task('styleguide', function () {
let output = global.isProd ? config.styleguide.prodDest : config.styleguide.dest,
processors = [
styleguide({
project: 'A awesome title',
dest: output + '/index.html',
})
],
return gulp.src('app/css/*.css')
.pipe(postcss(processors, {syntax: scss}))
});
the output bit is correct since the style guide file is generated.
This plugin would be really really good if it worked for my next project. Thanks again if you have to look into it ;)
When a style guide is generated it contains css represented in the documentation, but is failing to apply styles to the elements in the guide. I created an example repo that demonstrates the issue
https://github.com/ronnross/sample-style-guide
When you run the example repo you will see the the Button has the correct .btn class, but the styles are never being loaded in the html page.
Here's my styleguide task.
var postcss = require('gulp-postcss');
var styleguide = require('postcss-style-guide');
var postcssimport = require('postcss-import');
gulp.task('styleguide', function () {
gulp.src(path.css_src + '**/*.css')
.pipe(postcss([
precss(),
postcssimport(),
styleguide({
project: 'styleguide',
dest: './styleguide/index.html'
})
]))
});
styleguide task seems to be working, tho nothing is printed in the generated HTML file.
[11:03:03] Starting 'styleguide'...
[11:03:03] Finished 'styleguide' after 5.85 ms
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Successfully created style guide!
Any thoughts on what I might be doing wrong?
I propose a new feature.
var styleGuide = require('postcss-style-guide')
var themeName = 'foo'
postcss().use(styleGuide(themeName, options)).process(css).css
The theme module is named psg-theme-foo
. psg-theme-
is prefix of themes.
The theme template have to be written by ejs.
It's quite impossible to define a larger guide structure.
It would have been great if we could have a parser for at least '@subtitle' if not for more heading types.
Thanks to a friendly Twitter reply in my search of a style guide tool that handles CSS Selector Level 4 variables, I found your repository and like what you are doing.
Since I started using KSS-Node some weeks ago, a very popular style guide generator, I would like to share my experience. I already started building themes for kss-node styleguide, so I might had some deeper look into it. I didn't use postcss-style-guide before, so my knowhow comes out of your documentation.
First of all, KSS itself just defines the way of documenting CSS. Out of the box, it's more like a spec for the syntax. Then it includes Ruby gems to generate the style guides built with the specified syntax, but it's not needed.
kss-node brings those features to the node environment, making it possible to build style guides without the need of ruby.
So the important point here is, the documentation just works and makes sense even without generating a style guide. This is an important point because in programming, documenting your functions an classes are not meant to generate documentation in a first instance.
Additionally if have features to control the output of a possible styleguide. For example, I can add a weight
property to order the output, or I can add a Styleguide 1.1.2
or Styleguide Components.Buttons
to group my definitions in chapters, which is very handy. I'm also able to write markup inline like in postcss-style-guide, but can also add it to a .html file and reference it with Markup: mymarkup.html
which is kind of a must for big HTML structures.
So I would like to give some feature ideas for your library since I'm very interested documenting my projects which all use CSS Selector Level 4 stuff.
@styleguide
definition in the header. It's repeating and doesn't add value for the documented piece of code itself, so it shouldn't exist or at least not placed at the start. It's kind of secondary annotation, similar to Angular's @nginject
. You're also able to find styleguide comments by searching for the @title
annotation.@title
for the title, so I expect using the same for the description e.g. @description
. Or do it like kss and drop any of those annotation tags. But to be honest, I like your solution with the @
chars because it's identical to most programming languages' documentation syntax.The main reason why I'm coming up with this in your repository is, the KSS repository seems to have a lack of maintainers and pull request are kind of ignored at the moment, so chances are small to extend it for CSS Selector Level 4 variables.
Thanks for reading and your work and I hope you can use some of my inputs.
When I created a theme and then I try to use it but I got a error blow.
s.js:565
fs.write = function(fd, buffer, offset, length, position, callback) {
^
Error: ENOENT, no such file or directory '/path/to//Desktop/test/node_modules/postcss-style-guide/node_modules/psg-theme-simple/template.ejs'
at Error (native)
at Object.fs.openSync (fs.js:500:18)
at Object.fs.readFileSync (fs.js:352:15)
at /path/to/Desktop/test/node_modules/postcss-style-guide/index.js:20:27
at creator (/path/to/Desktop/test/node_modules/postcss-style-guide/node_modules/postcss/lib/postcss.js:56:39)
at Object.<anonymous> (/Users/sota/Desktop/test/index.js:12:10)
at Module._compile (module.js:460:26)
at Object.Module._extensions..js (module.js:478:10)
at Module.load (module.js:355:32)
at Function.Module._load (module.js:310:12)
It's very good job and style guide works very well . Do you think it would be possible with an option (enabled of disabled) to add the link of CSS in the style guide generated and display element ?
Does it work with inline comments (//
)?
So like this example:
// # I love Twitter Bootstrap
//
// Use the button classes on an `<a>`, `<button>`, `<input>` element.
//
// <button class="btn">Button</button>
//
// <button class="btn">Button</button>
.btn {
...
}
.btn:hover,
.btn:focus,
.btn.focus {
...
}
Running Windows 8.1
Node 5.1
I get this error.
Module build failed: Error: ENOENT: no such file or directory, open 'C:\dev
000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWebsite\fe-tooling\node_modules\highl
ight.js\styles\github.css'
at Error (native)
at Object.fs.openSync (fs.js:584:18)
at Object.fs.readFileSync (fs.js:431:33)
at generate (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWebsite\f
e-tooling\node_modules\postcss-style-guide\index.js:79:24)
at C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWebsite\fe-tooling
node_modules\postcss-style-guide\index.js:71:9
at LazyResult.run (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWeb
site\fe-tooling\node_modules\postcss\lib\lazy-result.js:201:20)
at C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWebsite\fe-tooling
node_modules\postcss\lib\lazy-result.js:115:37
at LazyResult.asyncTick (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.
PwsWebsite\fe-tooling\node_modules\postcss\lib\lazy-result.js:129:15)
at processing.Promise.then._this2.processed (C:\dev\000_WebPWS\j6\WebPWS
\Private\Project\j6.PwsWebsite\fe-tooling\node_modules\postcss\lib\lazy-result.j
s:155:20)
at LazyResult.async (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsW
ebsite\fe-tooling\node_modules\postcss\lib\lazy-result.js:152:27)
at LazyResult.then (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6.PwsWe
bsite\fe-tooling\node_modules\postcss\lib\lazy-result.js:75:21)
at Object.module.exports (C:\dev\000_WebPWS\j6\WebPWS\Private\Project\j6
.PwsWebsite\fe-tooling\node_modules\postcss-loader\index.js:43:32)
if I change line 79 from this
var codeStylePath = path.join('node_modules', 'highlight.js')
to this
var codeStylePath = path.join(__dirname,'node_modules', 'highlight.js')
it works fine,
Is there something I'm missing?
gulp.task('css', function() {
return gulp.src('css/core.css')
.pipe(postcss([
require('postcss-import')({
path: __dirname + '/css/'
}),
require('postcss-nested')(),
require('postcss-extend')(),
require('postcss-simple-vars')(),
require('postcss-calc')(),
require('postcss-color-function')(),
require('autoprefixer')(),
require('lost')(),
require('postcss-at2x')(),
require('postcss-style-guide')({
showCode: true,
name: '66pix',
dir: 'styleguide'
})
]))
.pipe(gulp.dest('public/css'));
});
[19:47:18] Error: ENOENT: no such file or directory, open '/Users/faceleg/Sync/faceleg/Work//services/web-frontend/node_modules/postcss-style-guide/node_modules/psg-theme-default/template.ejs'
at Error (native)
at Object.fs.openSync (fs.js:584:18)
at Object.fs.readFileSync (fs.js:431:33)
at /Users/faceleg/Sync/faceleg/Work//services/web-frontend/node_modules/postcss-style-guide/index.js:34:27
at creator (/Users/faceleg/Sync/faceleg/Work//services/web-frontend/node_modules/postcss/lib/postcss.js:60:39)
at Function.postcss.plugin (/Users/faceleg/Sync/faceleg/Work//services/web-frontend/node_modules/postcss/lib/postcss.js:66:23)
at Object. (/Users/faceleg/Sync/faceleg/Work//services/web-frontend/node_modules/postcss-style-guide/index.js:12:26)
at Module._compile (module.js:425:26)
at Object.Module._extensions..js (module.js:432:10)
at Module.load (module.js:356:32)
The following gulp task throws Error: postcss-style-guide: <css input>:1:1: Unknown word output.css
gulp.task('guide', function() {
var processedCSS = 'output.css';
return gulp.src('src/*.css')
.pipe(require('gulp-postcss')([
require('postcss-style-guide')(processedCSS, {
name: "Project Name"
})
]))
.pipe(gulp.dest('build/'));
});
The css is taken directly from the gulp example in the readme. Any idea what is causing the error?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.