node-sassdown
Node library for building living styleguides with Handlebars from Markdown files and Markdown comments in CSS or Sass files.
Note: This library is highly inspired by node-sassdown which itself is based on sassdown version 0.2.7 by Jesper Hills.
This version is introducing the following new features :
- Add a powerful default theme based on the UI of AREA17 Guides
- Adding configuration options to change orders of sections and subsections and customize titles. Create a yml file with the same name, see _grid.scss.yml for example.
- Generate single page or page based toolkits. Check options.singlePage for usage
- You can add introduction/index to any folders. See index.md for example.
- Move away from grunt
Documentation
Getting started
Install this library with this command:
npm install @antoine_a17/a17-node-sassdownUsage
Import the library in your file and initialize it
var sassdown = require('@antoine_a17/a17-node-sassdown');
var srcPath = 'assets/scss';
var destPath = 'styleguide';
var options = {};
//generate styleguide
sassdown(srcPath, destPath, options);Arguments
srcGlob
Type: String|Array
Default: null
A glob path or an array of filepaths
srcPath
Type: String
Default: null
Root folder of source files (used as cwd option in glob )
destPath
Type: String
Default: null
Root folder of generated styleguide
options
Type: Object
Default: {}
Styleguide options. See below for details
Options
options.assets
Type: Array
Default: null
Optional. Array of file paths. Will be included into the styleguide output. Supports globbing. Supports relative and absolute file paths (eg. http://, https://, // or even file://).
options.template
Type: String
Default: null
Optional. A path to a Handlebars template file. Will use default Sassdown template if left blank.
options.handlebarsHelpers
Type: Array
Default: null
Optional. Array of file paths. The Handlebars helpers will be available to use in the template. Supports globbing. Supports relative and absolute file paths (eg. http://, https:// or even file://).
options.theme
Type: String
Default: null
Optional. A path to a theme folder (containing JS/CSS/fonts/images files). Will use default Sassdown theme based on guides.area17.com UI if left blank.
options.readme
Type: String
Default: null
Optional. Path to a README file. When set, this file will be parsed with Markdown and used as the index page for the styleguide.
options.highlight
Type: String
Default: github
Optional. Choice of syntax highlighting style. Defaults to github, but other available options are: docco, monokai, solarized-light, solarized-dark or xcode.
options.commentStart
Type: RegExp
Default: /\/\*/
Optional. A regular expression to match beginning part of a comment block. Defaults to regular block comment (/*).
options.commentEnd
Type: RegExp
Default: /\*\//
Optional. A regular expression to match ending part of a comment block. Defaults to regular block comment (*/).
options.excludeMissing
Type: Boolean
Default: true
Optional. When set to true, Sassdown will ignore any files that do not contain matching or valid comment blocks.
options.dryRun
Type: Boolean
Default: false
Optional. When set to true, Sassdown will not generate any files, and will exit with status 1 if any files do not contain matching or valid comment blocks.
options.singlePage
Type: Boolean
Default: true
Optional. When set to true, Sassdown will only generate an index file. This is useful when you use a theme that is a one-page documentation.
Markdown
Sassdown uses Markdown to parse any block comments in your Sass files. From these, it generates the text content in the styleguide. Any recognised code blocks will be rendered as HTML/SCSS source-result pairs.
Structure
You may use any Markdown-compatible heading syntax you like. You may use any common style of block-comment syntax you like. Code blocks may be fenced or indented (four spaces or one tab character). Below are several examples; each will be correctly parsed by Sassdown into identical output.
Example .scss file
/*
Alerts
======
Creates an alert box notification using the `.alert-` prefix. The following options are available:
<div class="alert-success">Success</div>
<div class="alert-warning">Warning</div>
<div class="alert-error">Error</div>
*/
@mixin alert($colour){
color: darken($colour, 50%);
background: $colour;
border-radius: 5px;
margin-bottom: 1em;
padding: 1em;
}
.alert-success { @include alert(#e2f3c1) }
.alert-warning { @include alert(#fceabe) }
.alert-error { @include alert(#ffdcdc) }Handlebars
Handlebars is a semantic templating syntax. Put simply, it allows you to output dynamic properties in HTML using {{var}} from a variety of data sources such as JSON.
Sassdown uses Handlebars to output data from the data objects it creates. Your .hbs file specified in the template option may contain code that looks like this for example:
{{#each page.sections}}
<div class="section">
{{#if comment}}
<div class="comment">{{{comment}}}</div>
{{/if}}
{{#if result}}
<div class="result">{{{result}}}</div>
{{/if}}
{{#if markup}}
<div class="markup">{{{markup}}}</div>
{{/if}}
{{#if styles}}
<div class="styles">{{{styles}}}</div>
{{/if}}
</div>
{{/each}}Common partials
Sassdown also provides a series of Handlebars partials, which can be used to output specific information on each page. These are:
-
{{> root}}
Outputs a path to the root directory of the styleguide, relative to whatever page you are on. -
{{> assets}}
Outputs a set of<link />or<script>tags that include assets specified in the Grunt task options.
Handlebars helpers
You can add more features to Handlebar templates by using Helpers.
For example you could add a helper that capitalizes all text:
<big>{{uppercase shoutThis}}</big>
You load your helpers with the handlebarsHelpers option.
handlebarsHelpers: ['hb-helpers/**/*.js']
The helper module must export a function that does the registration, or else it won't load.
module.exports = function(Handlebars) {
Handlebars.registerHelper('uppercase', function(input) {
return typeof input === 'string' ? input.toUpperCase() : input;
});
};
// This also works
module.exports = {
register: function(Handlebars) {
...
}
The following helpers are already included by default :
- capitalize
- lowercase
- strip_num (Remove numbers that are at the beginning of words)
- titlecase
- urlify (turn text into valid url strings)
Highlight.js
Sassdown uses the popular and well-supported Highlight.js for syntax highlighting. Markup is parsed by a Node module and highlighted before being output through the template. Various popular themes are supported via the task options.
Data Objects
Two objects are parsed into the Handlebars template; Page and Pages. Page contains json data for the current page only; Pages is an array literal containing all Page objects in a nested node tree.
Any property within these objects can be output by Handlebars using {{helpers}}. You can iterate through objects using {{#each}} ... {{/each}}, for example.
Page
{
title: 'Alerts',
slug: '_alerts',
href: 'objects/user/_alerts.html',
dest: 'test/example/styleguide/objects/user/_alerts.html',
src: 'test/example/assets/sass/partials/objects/user/_alerts.scss',
position: 0,
sections: [
{
id: 'mswbu',
comment: '<h1 id="alerts">Alerts</h1>\n<p>Creates an alert box notification using the <code>.alert-</code> prefix. The following options are available:</p>\n',
result: '\n<div class="alert-success">Success</div> \n<div class="alert-warning">Warning</div> \n<div class="alert-error">Error</div>\n',
markup: '<pre><code><span class="token tag" ><span class="token tag" ><span class="token punctuation" ><</span>div</span> <span class="token attr-name" >class</span><span class="token attr-value" ><span class="token punctuation" >=</span>"alert-success"></span></span>Success<span class="token tag" ><span class="token tag" ><span class="token punctuation" ></</span>div</span><span class="token punctuation" >></span></span> \n<span class="token tag" ><span class="token tag" ><span class="token punctuation" ><</span>div</span> <span class="token attr-name" >class</span><span class="token attr-value" ><span class="token punctuation" >=</span>"alert-warning"></span></span>Warning<span class="token tag" ><span class="token tag" ><span class="token punctuation" ></</span>div</span><span class="token punctuation" >></span></span> \n<span class="token tag" ><span class="token tag" ><span class="token punctuation" ><</span>div</span> <span class="token attr-name" >class</span><span class="token attr-value" ><span class="token punctuation" >=</span>"alert-error"></span></span>Error<span class="token tag" ><span class="token tag" ><span class="token punctuation" ></</span>div</span><span class="token punctuation" >></span></span></code></pre>\n',
styles: '<pre><code><span class="token keyword" >@mixin</span> alert(<span class="token variable" >$colour</span>)<span class="token punctuation" >{</span>\n <span class="token property" >color</span><span class="token punctuation" >:</span> darken(<span class="token variable" >$colour</span>, 50%)<span class="token punctuation" >;</span>\n <span class="token property" >background</span><span class="token punctuation" >:</span> <span class="token variable" >$colour</span><span class="token punctuation" >;</span>\n <span class="token property" >border-radius</span><span class="token punctuation" >:</span> 5px<span class="token punctuation" >;</span>\n <span class="token property" >margin-bottom</span><span class="token punctuation" >:</span> 1em<span class="token punctuation" >;</span>\n <span class="token property" >padding</span><span class="token punctuation" >:</span> 1em<span class="token punctuation" >;</span>\n<span class="token punctuation" >}</span>\n\n.alert-success <span class="token punctuation" >{</span> <span class="token keyword" >@include</span> alert(#e2f3c1) <span class="token punctuation" >}</span>\n.alert-warning <span class="token punctuation" >{</span> <span class="token keyword" >@include</span> alert(#fceabe) <span class="token punctuation" >}</span>\n.alert-error <span class="token punctuation" >{</span> <span class="token keyword" >@include</span> alert(#ffdcdc) <span class="token punctuation" >}</span></code></pre>\n'
}
]
}Pages
[
{
name: 'base',
title: 'base',
isDirectory: true,
pages: [
[Object],
{
name: 'typography',
isDirectory: true,
pages: [
[Object],
[Object],
[Object]
]
},
[Object],
[Object]
]
},
{
name: 'partials',
isDirectory: true,
pages: [
[Object],
[Object]
]
},
{
name: 'modules',
isDirectory: true,
pages: [
[Object]
]
},
{
name: 'objects',
isDirectory: true,
pages: [
[Object],
[Object],
[Object]
]
}
]Template
Single Page If you want to customize the default template, you may wish to use the existing default template.hbs as a base to work from.
Multiple Page If you don't want to use a single page templates : you can the existing default template_multipage.hbs as a base.
The default multiple page theme is using pjax to refresh page (with Barba.js).
Sass
It should be noted that, despite the name, Sassdown does not explicitly read only Sass files. It works just fine with .sass, .less, .css or even .txt files.
Sassdown does not compile your source files.