The following sections describe the basics of authoring documentation.

A piece of KSS documentation is essentially a comment block, within the stylesheet, written in a specific way.

The bare minimum that will generate a section in the style guide is as follows.

// Title
//
// Description
//
// Styleguide Root.Section

First of all, take note of the empty lines in-between as they demarcate the structure of the section and need to be present in order for kss-node to be able to distinguish parts of the section.

• Title refers to the title of the section and the name of the nav item in the navigation menu.
• Description marks the area where the content of the section lies.
• Styleguide is a special keyword that needs to be followed by an index. It enables kss-node to know how the section should be indexed — in this case, Root.Section. The keyword is case-insensitive and therefore, can be written as styleguide (but not recommended). Use of the Styleguide keyword should be limited to the bottom of a section's documentation as it marks the end of the section.

Indexes can be named any way you wish, with leading words (separated by the dot) denoting hierarchy. They control how your documentation will be structured in the style guide and can also accept numbers, like 1.1.12.

📝 Note: Any leading words that do not refer to an existing section are created automatically as empty sections.

A more concrete example of a section may look like this:

// Components
//
// Wonderful components to use in the app!
//
// Styleguide Components

And a subsection, documenting a component, may look like this:

// My Component
//
// An awesome component!
//
// Styleguide Components.MyComponent

.my-component { ... }

📝 Note: Block-style comments are usually used to wrap the documentation. However, an example cannot be shown here due to conflicts with the SASS compiler for using comment blocks recursively (because this section itself is written within a comment block). As such, examples that demonstrate the KSS syntax will only be written using // comment style.

By default, sections are sorted by their indexes in alphabetical order within the same hierarchical level. The subject of controlling this behavior will be touched on in a later section.

Contents of the documentation are authored using markdown.

You can also use HTML within markdown, for example, underlining using <u> or forcing a line break using <br>.

📝 Note: The markdown parser may at times produce unexpected results even when the valid markdown syntax is used. This usually happens for line breaks or when applying markdown formatting with an asterisk * before the first word in a line/paragraph.

Start example

Markdown Code

__Lorem__ ipsum **dolor** sit *amet*, consectetur adipiscing elit.
[Curabitur](https://www.google.com) laoreet risus in risus volutpat, eu mollis risus ***elementum***.
Duis non sagittis diam.<br>
Etiam convallis vel est eget sagittis.
<u>Nam suscipit</u>, nisl bibendum fermentum ultrices, nisi ~~enim rutrum ex~~, a dignissim nisl tellus id [tortor].

[tortor]: https://www.google.com

Result

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur laoreet risus in risus volutpat, eu mollis risus elementum. Duis non sagittis diam.
Etiam convallis vel est eget sagittis. Nam suscipit, nisl bibendum fermentum ultrices, nisi enim rutrum ex, a dignissim nisl tellus id tortor.

End example

🛑 Important: In the above example, underscores _ were used instead of * to format "Lorem" as bold. If the latter was used, it would not have produced the expected result — refer to the earlier note. In general, it is better to use _ over * to get fail-safe and consistent results.

A live example and its markup code can be displayed in a section using Markup.

It can be written as follows.

// ...
//
// Markup: <button class="kss-demo kss-demo-btn">Button</button>
//
// ...

Or it can be spread over multiple lines like this.

// ...
//
// Markup:
// <button class="kss-demo kss-demo-btn">
//     Button
// </button>
//
// ...

🛑 Important: When spreading over multiple lines, there must not be any empty lines in-between the markup code or it will not render correctly.

This will render 2 more panels at the bottom of the section:

• Example block which displays a live example of the component, and
• Markup block which displays the HTML markup that is used to render the example.

💡 Tip: If you only wish to render the example but not the markup code, you can explicitly hide the markup code using HideMarkup.

Sections of the style guide are sorted by their indexes, in alphabetical order. This, however, is not always the desired effect.

To exercise control over the ordering of sections, Weight can be used to define the relative order of a section. And, it works like physical weight, i.e. heavier stuff sinks to the bottom.

// ...
//
// Weight: 2
//
// ...

By default, the Weight of a section is 0 if not specified anywhere in the section. It can be assigned to any integer values like 1000, including negative ones like -10.

📝 Note: If 2 sections are at the same hierarchical level and have the same resulting weight, then they will be ordered alphabetically according to their index names.

Here's an example.

// Section A
//
// This is section A.
//
// Weight: 9
//
// Styleguide SectionA

...

// Section B
//
// This is section B.
//
// Weight: 8
//
// Styleguide SectionB

In the above example, the natural sorting order is Section A followed by Section B. However, due to the use of weights, Section B will be ordered before Section A since the former weighs lesser.

The following sections describe more advanced documentation capabilities.

The Colors block can help to document used colors into a color palette.

// ...
//
// Colors:
// ColorName: #38b21f - Description
// $clr-primary: #0d6efd - Primary color
// Indigo: #4d0dce
// rgb(212, 17, 50)
// hsl(43, 100%, 53%) - HSL
//
// ...

This will render a color palette (as shown below) displaying:

• the name of the color,
• the value of the color, and
• a description.

📝 Note: Only the color value is required.

Parameters can be handy for documenting any APIs like SASS mixins, functions, etc.

For example, it can be used to document a contrived mixin linear-gradient() like this:

// linear-gradient($from, $to, $direction)
//
// Renders a linear gradient as background.
//
// $from - Color from.
// $to - Color to.
// $direction = to right - Direction of gradient.
//
// Styleguide Mixins.LinearGradient

@mixin linear-gradient($direction, $from, $to) { ... }

🛑 Important: The following should be kept in mind when using Parameters.

1. Parameters must always be used after descriptions or they will not render correctly. Also, the block will always be rendered at the end of the section.

2. When Markup is already used in a section, any following Parameters will be parsed by kss-node as Modifiers — this means Markup and Parameters blocks cannot coexist within a single section.

3. Parameters is tailored towards documenting SASS functions and mixins. In other cases where it is desirable to display information in a Parameters-like fashion, it is generally better to use Legend.

In the earlier example, the Parameters that were defined are:

// ...
//
// $from - Color from.
// $to - Color to.
// $direction = to right - Direction of gradient.
//
// ...

This renders a Parameters block (as shown at the bottom of the section).

💡 Tip: You can change the title of the Parameters block using ParamsTitle.

Modifiers help document and render the states/variants of a component, by using a single copy of markup code. They are essentially the combination of Markup and Parameters used within a section.

// ...
//
// Markup:
// <button class="kss-demo kss-demo-btn {{modifier_class}}">Button</button>
//
// :hover - Highlights when the mouse is hovered over the button
// :active - Highlights when the mouse button is clicked down on the button
// :focus - Highlights when the button receives the focus
//
// ...

This will render 2 more panels in the section (as shown below):

• Examples block which displays live examples of the component used with the given modifiers, and
• Markup block which displays the HTML markup that is used to render each example.

💡 Tip: You can hide the Default styling item using HideDefault.

Partials allows for the Markup of a section, by making use of those from other sections by referencing their index names.

The following example shows how the markup in another section can be referenced for use in this section.

// ...
//
// Markup:
// <div style="background-color: #eee; padding: 1rem">
//   {{> DocumentationGuide.Basics.Markup }}
//   Some text
// </div>
//
// ...

💡 Tip: You can see the index name of a section by hovering your mouse pointer over the section number (at the top of each section) in the style guide.

Legend can be used to render a list of terms and their definitions. Both the terms and definitions can use markdown for formatting.

// ...
//
// Legend:
// _Term 1_ :: The term is _italicized_.
// __Term 2__ :: The term is __bolded__.
// `Term 3` :: The term is formatted within `<code>`.
//
// ...

It will render a Legend block displaying a list of terms and their corresponding definitions (as shown below).

🛑 Important: Unlike Parameters which is required to be used after descriptions, Legend can be used between descriptions. However, the Legend block will always be rendered after the contents in the description (and not where it is used).

💡 Tip: You can change the title of the Legend block using LegendTitle.

Use [#index_name | title] in description to create a link to another section using its index name. The title will be extracted from last part of the index name if not provided.

📝 Note: You can also use them in the item descriptions of Parameters and Legend blocks.

Start example

Code

// ...
//
// This is a link to [#DocumentationGuide.Basics]
//
// This is a link to [#DocumentationGuide.Basics | The Basics Section]
//
// ...

Result

This is a link to Basics

This is a link to The Basics Section

End example

💡 Tip: Referencing an invalid section will produce a warning message in the CLI terminal to alert you. However, this will not prevent the style guide from being built.

HighlightMarkup allows basic regular expressions (i.e. no fancy stuff like look ahead, look behind, etc) to be used to highlight keywords in the Markup block.

🛑 Important: Only applicable to CSS classnames that are found within the class attribute.

// ...
//
// HighlightMarkup: kss-demo(-\w+)?
//
// Markup: <button class="kss-demo kss-demo-btn">Button</button>
//
//...

Notice that in the Markup block, the CSS classnames kss-demo and kss-demo-btn are highlighted.

📝 Note: Remember to properly escape special characters (with a \) if you intend to use them as literal characters.

💡 Tip: It also works with Partials.

The following sections describe the less prominent (but not necessarily less useful) documentation capabilities.

Deprecated is used to put up a deprecation notice in the section.

📝 Note: kss-node exposes a {boolean} for this property in the template .hbs. When iterating over sections using {{#each sections}}, the value can be accessed like {{#if experimental}} ... {{/if}} to customize the template. However, it is not currently used to augment anything in this style guide.

Start example

Code

// ...
//
// Deprecated: This style has been deprecated and will be removed in the next
// major release.
//
// ...

Result

⚠️ Deprecated: This style has been deprecated and will be removed in the next major release.

End example

Experimental is used to put up an experiment notice in the section.

📝 Note: kss-node exposes a {boolean} for this property in the template .hbs. When iterating over sections using {{#each sections}}, the value can be accessed like {{#if experimental}} ... {{/if}} to customize the template. However, it is not currently used to augment anything in this style guide.

Start example

Code

// ...
//
// Experimental: This is an experimental CTA for AB testing.
//
// ...

Result

🧪 Experimental: This is an experimental CTA for AB testing.

End example

Embellishment is used to decorate specific text patterns in order to draw more attention to them.

By default, kss-node displays Deprecated and Experimental as vanilla text (see KSS Spec). However, as such notices tend to warrant some special attention, so it makes sense to make them appear more noticeable.

Embellishments are only applied to the text patterns matching at the start of a line/paragraph and can be configured in styleguide.config.js.

// styleguide.config.js
const config = {
  ...,
  authoringFeatures: {
    embellishments: {
      // [key: string]: [embellishment: string]
      deprecated: "⚠️",
      experimental: "🧪",
      ...
    },
  },
  ...,
}

module.exports = config

The transformed text and its decoration are also wrapped in a CSS selector .lss-{key} to provide for optional styling via CSS. key is the key (used as text pattern) mapping to a corresponding decoration and will always appear as lowercased in .lss-*.

Out-of-the-box, living-styleguide-skeleton comes with the following embellishments:

HideDefault is used to disable the rendering of the default example when using Modifiers.

// ...
//
// <button class="kss-demo kss-demo-btn {{modifier_class}}">Button</button>
//
// :hover - Highlights when the mouse is hovered over the button
// :active - Highlights when the mouse button is clicked down on the button
// :focus - Highlights when the button receives the focus
//
// HideDefault:
//
// ...

Notice that in the below example block, no Default styling item is generated.

HideMarkup is used to render only the example — and not render the markup code — when using the Markup.

// ...
//
// Markup:
// <button class="kss-demo kss-demo-btn">Button</button>
//
// HideMarkup:
//
// ...

Notice that no markup code is rendered for the example below.

LegendTitle is used to render a different block title — when using Legend — to better reflect the intent of the information.

// ...
//
// LegendTitle: Options
//
// Legend:
// `step` :: Any integer from `1` to `12` as a factor of `0.25em` increments.
// `state` :: Any state in `{hover|active|focus}`.
//
// ...

Notice that the title of the Legend block (below) has been changed.

ParamsTitle is used to render a different block title when using Parameters.

// ...
//
// ParamsTitle: Key / Value
//
// "primary" - Primary color scheme `{map}`.
// "primary"."color" - `#3b82f6`
// "primary"."text" - `#fff`
// "secondary" - Secondary color scheme `{map}`.
// "secondary"."color" - `#94a3b8`
// "secondary"."text" - `#fff`
//
// ...

Notice that the title of the Parameters block (below) has been changed.

The following sections describe additional features that assist documentation authoring.

Although Weight is incredible for fine-grain control over the ordering of sections, a major pain point when using it is not knowing how weights were distributed across sections — without having to painfully plough through each individual source file.

Therefore, when in the development environment, Section Weights are automatically displayed alongside their corresponding nav menu items to provide a bird's eye view of weight information.

🛑 Important: Section Weights are not rendered in the production build.

Example Helpers are additional CSS selectors that can be used to assist in the styling of examples.

All such selectors are prefixed with a sg-.

Use .sg-font-wireframe to apply a wireframing typeface to your text examples.