Making UI documentation a bit sweeter ✨
Sugarcoat was created to enable developers to produce rich UI documentation easily and with minimal up-keep. Sugarcoat works by parsing project files for documentation comments (similar to JavaDoc, JSDoc, etc.) and generates a responsive HTML site or JSON that is organized and easy to read. Sugarcoat allows developers and designers access to up-to-date previews of UI elements, page components, project specific colors and typography, all in one place.
Note: This is still a work in-progress. Please file an issue if you encounter any issues or think a feature should be added.
Sugarcoat will never force a file/project structure on you, nor make you create extra files for it to work.
Sugarcoat parses all comment blocks in the file(s) you specify with JSDoc commenting syntax. Or you can specify your own delimiters.
If you declare CSS modifier states within your comment block, Sugarcoat will highlight and display them in your pattern library for extra readability.
Sugarcoat will understand your variables if they're SCSS, LESS, or CSS Custom Property
Sugarcoat allows you to define your own layout, partials and assets.
npm install --save sugarcoat
The Sugarcoat module takes a
config object and returns a
Promise. The Promise resolves to the original
config object, expanded to contain the data from your parsed sections.
const sugarcoat = ;;// or;
You can also install the Sugarcoat command globally (via
npm install -g sugarcoat). The
sugarcoat command takes a path to a configuration file which must export the configuration object.
sugarcoat [flags] <configuration file>Options:-h, --help output usage information-V, --version output the version number
settings:dest: 'path/to/dest'sections:title: 'Base'files:'path/to/styles/typography/*.css''path/to/styles/variables/*.css'title: 'UI'files: 'path/to/styles/molecules/**/*.css'
This object holds general configuration values.
Path to which
dest is relative.
Directory to which Sugarcoat will output the results. This path is relative to
cwd. Sugarcoat will create any directories that do not already exist.
Path to the image to be rendered in the heading of your pattern library.
Configure Sugarcoat's logging properties. See npm/npmlog for more info.
CSS file(s) you wish Sugarcoat to prefix with
prefix.selector. The newly prefixed stylesheets will be placed in your document in the order you declare them.
Define the selector to be used to prefix all assets from
prefix.assets. Should a user choose to develop their own pattern library templates, they can designate their own selector prefix.
The base path to which all
template paths are relative.
main.hbs(provided by Sugarcoat)
Path to the Handlebars layout that will define the layout of the site.
Partial file(s) to register with Handlebars. If any partials use a reserved name, the respective partial will override the one provided by Sugarcoat.
Static asset file(s) to copy to
settings.dest. If you would like to use Sugarcoat's default pattern library assets, as well as your own, just include
sugarcoat in the asset array.
The value displayed as the heading of your pattern library.
Array of Section Objects.
Each section object in the sections array is rendered as a category. Each comment block within all files in your section object is rendered as a subcategory. You can modify the
mode Sugarcoat uses to parse the files in your section object, as well as the
template it uses to render the parsed data.
Heading of the section.
By default, all files are parsed only for their comment blocks. By using
'variable' mode, Sugarcoat will parse your stylesheet's variable declarations as well. This works with variables prefixed with
--, depending on the stylesheet's file extension.
The default partial name used to display parsed comments is
mode is provided, the default partial name used is
mode has two alternate variable renderings available:
section-typography. If you'd like this section to use a custom partial, provide its name to this option. Be sure to register your custom partial in settings.template.partials`. For more information on this, see Custom Templating.
|undefined||'section-default'||Parse comment block only|
|'variable'||'section-variable'||Parse file content for variables and renders a simple table. Inline comments are treated as the variable's description. Groups of variables can be divided in a file by a comment block.|
|'variable'||'section-color'||Same as 'section-variable', except variables are rendered as swatches|
|'variable'||'section-typography'||Same as 'section-variable', except font-family styles are applied to sample text|
Parse all variables in my file:
title: 'Project Defaults'files: 'path/to/global/vars.scss'mode: 'variable'
Parse all variables in my file and render them using the 'section-color' partial:
title: 'Colors'files: 'path/to/global/colors.scss'type: 'variable'template: 'section-color'
Throughout Sugarcoat we use a standardized format for files. This format allows the user to express a file in three different ways:
A path or pattern (Globby) to a location.
files:'path/to/main.js'src: 'path/to/main.js'options:nodir: true
Provide more globbing options in addition to the standardized patterns. See Globby.
files:src: 'path/to/main.js'options:nodir: true
/*** @title Tooltip* @example* <div class="tooltip">* <span class="tooltip-content">This is a tooltip</span>* </div>* @modifier .active enabled class on .tooltip* @state :focus allows visual contrast for accessibility*/
Sugarcoat will parse any tag it finds into a key/value pair. For example:
The exception being the following three reserved tags that are demonstrated in the above example:
@example Takes a single or multiline code example.
@modifier Used for a class modifier on a component:
@modifier <selector> <description>.
@state Used for state pseudo-classes such as
@state :<pseudo-class> <description>.
For html files, Sugarcoat uses the same comment style. Since HTML doesn't support this style you'll need to wrap your documentation comments with an HTML-style comment.
Comment Example (html)
<!--/*** @title Some Component* @description This component has a description* @dependencies /path/to/some-component.js*/-->I'm a Component!