Comments (14)
I would like to add this from http://warpspire.com/kss/syntax/
Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.
The parameters section
If the mixin takes parameters, you should document each parameter and describe what sort of input it expects (hex, number, etc).
// $start - The color hex at the top.
// $end - The color hex at the bottom.
The compatibility section
You must list out what browsers this helper method is compatible in.
// Compatible in IE6+, Firefox 2+, Safari 4+.
If you do not know the compatibility, you should state as such.
// Compatibility untested.
from kss-node.
Just an update, with 0.3.6: modifiers are coming through as paragraphs, as are compatibility sections.
from kss-node.
I would just like to add that LESS mixins are not parsed correctly either. The entire parameters section just turns into a single line of text.
from kss-node.
+1 - I'm seeing this too.
from kss-node.
I found that adding ~
after my parameters list prevented kss-node
from outputting the each parameter as a modifier.
Example:
/*
Mixins: Grid - 2 column with gutter
Custom grid, fully fluid to 100% of the container
Usage:
* `@include grid-flexi-x2(66/407, 11/407, 330/407);`
Layout:
* 1 row, containing 2 columns, separated by 1 gutter
Parameters:
* `$col1_width_nounit` - width of first column, divided by total width of container
* `$gutter_width_nounit` - width of gutter, divided by total width of container
* `$col2_width_nounit` - width of last column, divided by total width of container
~
Markup:
<div class="debug">
<div class="grid-flexi-test">
<div class="col">
column 1
</div>
<div class="col">
column 2
</div>
</div>
<!-- /.grid-flexi-x2 -->
</div>
Styleguide 1.3
*/
from kss-node.
👍
from kss-node.
Hello, I too ran into this issue, my parameters output on one line as a paragraph. I use Sass, is there a workaround for Sass users? Thanks.
from kss-node.
As kss-node is interpreting the arguments as modifiers, it doesn't display them without a provided markup.
Oh! I was trying to figure out how to get kss-node to tell the difference between a preprocessor helper docblock and a regular docblock. And I think that's the key!
If the docblock has a block that looks like modifiers, but has no markup block, then kss-node can display those as parameters instead of modifiers.
from kss-node.
👍
from kss-node.
Fixed!
from kss-node.
Thanks :) - Is there any chance this could be published to npm before the full 2.0 checklist todo is done?
I'll install from the repo for now: npm install kss-node/kss-node
from kss-node.
@MadLittleMods You dont need to wait for the final v2 release, just wait till "2.0.0-alpha.5"
from kss-node.
I just tried the latest code and it doesn't seem to work. I am using Sass scss. Installed via: npm install kss-node/kss-node#master
I grabbed this example from the gh-pages demo, also on the KSS site
// Creates a linear gradient background, from top to bottom.
//
// $start - The color hex at the top.
// $end - The color hex at the bottom.
//
// Compatible in IE6+, Firefox 2+, Safari 4+.
@mixin gradient($start, $end){
...
}
The only way I can get it to parse is if I add a // Styleguide 6.4
section declaration on the last line.
In that example, kss-node uses the description as the the header
.
If I add a a header(which is repetitive because it is right there in the mixin), then it lumps the description, parameters, and compatibility into the description
. I see that @JohnAlbin added a section declaration in his commit and a title.
Should it work without a header?
Also there is a kssParameter
which is available through kssSection.parameters()
but there is no compatibility method to retrieve the "Compatible in" section. Is this assumed to be lumped in with the description
.
from kss-node.
FYI, I'm using this feature already on a production web site. It's included with https://github.com/kss-node/kss-node/releases/tag/v2.0.0-beta.1
I've already opened a github discussion in the kss queue about the problem with showing a preprocessor example that doesn't have a Styleguide [ref]
declaration. https://github.com/kneath/kss/pulls How does that even make sense? If a CSS comment doesn't have a Styleguide [ref]
how can it be a KSS doc block? How would any kss parser know where to put the documentation if the user doesn't define where in the style guide hierarchy the preprocessor docs should go. The spec is too vague here.
The latest docs I wrote for kss-node v2 include an annotated spec at https://github.com/kss-node/kss/blob/spec/SPEC.md . That spec is clearly noted in the README, but won't appear on the kss-node homepage until v2 is released and the master branch becomes the default branch (instead of 1.x.) That will happen sometime in the next week.
from kss-node.
Related Issues (20)
- 3 level navigation
- An in-range update of twig is breaking the build 🚨 HOT 1
- How can I forward options into twig.js?
- ScrollSpy conflict
- Define styleguide components in the template directly HOT 2
- Generate example html from SASS? HOT 1
- Use different builders for different sections of the styleguide?
- Does not work if not installed globally
- v3.0.1 failing with permissions issues HOT 6
- v.3.0.0 Update may require relative path changes to projects HOT 1
- kss not recognizing handlebars code HOT 1
- v3.0.1 outputs: "Version 9 of Highlight.js has reached EOL" HOT 9
- Node versions >= 14
- Update SASS in kss-node-handlebars-builder
- Add option to load JavaScript in rendered styleguide as ES6 module HOT 1
- Extending handlebars helpers not working. v3.1.0 HOT 1
- Question: Do I need to write any javascript to extend handlebars to register partials? HOT 2
- Can I show variables with encoded SVG icons in the styleguide without hard-coding the values?
- ::selection as a modifier HOT 1
- kss-node multiple markup on page?
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from kss-node.