OrchidKSS
Generate a living styleguide from annotated CSS, Sass, Scss, or LESS
About
KSS is a methodology for documenting your CSS and generating a styleguide which shows example usage of your stylesheets. This plugin implements a basic KSS parser and renders KSS blocks as Orchid pages as a living styleguide.
Demo
- Run KssGeneratorTest for demo
Usage
KSS are block comments placed within your stylesheets, an example is given below:
/*
A button suitable for giving stars to someone.
:hover - Subtle hover highlight.
.stars-given - A highlight indicating you’ve already given a star.
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
.disabled - Dims the button to indicate it cannot be used.
markup:
<li>
<a class="-modifierClass">Stars</a>
</li>
wrapper:
<ul>
-markup
</ul>
Styleguide 2.1.3.
*/
a.button.star {
}
a.button.star.star-given {
}
a.button.star.disabled {
}
These blocks are extracted from your stylesheets, and a hierarchy is built from their Styleguide References
(Styleguide 2.1.3. in the block above). Each section of the Styleguide gets its own page, which documents that section
and also all the sections of its immediate children.
The comment block contains several types of information that are inportant: the name, a description, modifiers,
and their descriptions, tags and their values, markup and wrapper templates, and a styleguide reference.
Styleguide Name
The first line in a KSS block should be the name of that styleguide section.
Styleguide Description
Any remaining lines in a KSS block that are not modifiers, tags, or the styleguide section are part of the section description. They do not need to be consecutive. Each Section becomes a Page, and the description becomes the "intrinsic content" of the page.
Modifiers
Modifiers are the specific CSS classes that give different styling to an element. Modifiers are a CSS selector on a line
by itself, with a short description which is separated from the selector by a -.
Tags
Tags are arbitrary data that can be used to configure the Section. Each Section becomes a Page, and tags become the
"Front Matter" of the page. Tags are a key on a line by itself ending with a :, everything that follows is the value.
Markup
Markup is just a Tag with a key of markup, whose value is HTML markup used to demonstrate usage of the element. This
markup is repeated in the Styleguide Section Page for each Modifier, and a placeholder of -modifierClass within the
markup is replaced with the modifier class.
Markup Wrappers
A Markup Wrapper extends the markup model for each child styleguide section. When creating the markup for a given
modifier, that section's markup is injected into its wrapper at the -markup placeholder. In addition, if the
section has a parent section, this markup is then injected into the parent section's markup at its -markup
placeholder, and this is done recursively for all parent sections. This helps to define logical hierarchies of markup
within your styleguide.
Styleguide Reference
Every KSS block describes a new section within your styleguide. These sections are intended to be described in a
hierarchy, and the Styleguide Reference is what builds that hierarchy. The sections are separated by . in the
reference, and this is then split up and built into the full sections hierarchy. These sections are commonly used just
as numbers to maintain a strict ordering, but they can be just normal names separated by . as well, such as
Styleguide UI.Buttons.Variants. for more logical groupings.
dependencies {
orchidRuntime("io.github.javaeden.orchid:OrchidKSS:0.18.0")
}
<dependency>
<groupId>io.github.javaeden.orchid</groupId>
<artifactId>OrchidKSS</artifactId>
<version>0.18.0</version>
<type>pom</type>
</dependency>
@file:DependsOn("io.github.javaeden.orchid:OrchidKSS:0.18.0")