KSS documentation

Custom KSS processing

KSS is used to parse KSS blocks in Sass files and extract raw documentation data, which then goes through some custom processing. Each section is processed like so:

1. Description is rendered as Markdown.
   • Code blocks are parsed using Highlights.
   • The default language for code blocks is TSX.
2. Markup is highlighted the same way as code blocks.
   • This happens at compile time, so the browser receives pre-highlighted HTML code.
3. Modifiers and parameters are not rendered as Markdown, but they are rendered "dangerously" in React so inline HTML is supported.
4. A number of @flags are supported in the description to augment the data object (detailed below)

After each section has been processed, a nested object is generated where each section contains its children (for instance, components.dialog.js is inside components.dialog which is inside components). This object is written to docs/build/docs.json.

All of this magic happens in the docs-kss gulp task defined in gulp/docs.js.

KSS @flags

Include these flags in the Markdown description of a section. They can be anywhere in the description and will be stripped from the rendered output, but it is suggested that they appear at the end for consistency.

The format for a flag is @[flag-name] [value]? where value is a string argument. If a flag accepts an argument, it is required.

/*
Section title

Markdown description...

@react-example DialogExample

Styleguide ref.ref.ref
*/

@hide-markup

Boolean flag to indicate that the raw HTML markup should not be shown after the rendered example.

@react-docs [ComponentName]

Render the given React component in the description for this section. ComponentName must be exported in docs/src/components/index.ts. The component cannot require any props or children as there's no way to provide them.

@react-example [ComponentName]

Render the given React component as the example for this section. ComponentName must be exported in docs/src/examples/index.ts. Component cannot require any props or children as there's no way to provide them. Additionally, filename must be docs/src/examples/[componentName].tsx for the "View source" link.

Page generation

docs/src/index.html is the master template for the single-page documentation app. The docs-wiredep task processes it to docs/build/index.html by adding bower dependencies using wiredep and injecting JSON data files into script blocks.

A quick glance reveals several blocks that look like this:

<script type="application/json" id="kss-data">
  ### DOCS ###
</script>

The ### NAME ### block is replaced with the contents of a JSON file with a similar name. The script block is then loaded and parsed by the React app. Docs data, icons, and package versions are all injected dynamically this way.