Documenting your code is a significant part of the development flow so you can’t neglect it. With the proper documentation, your codebase will be more futureproof. It is a real help if you are working alone and it is a huge help when you are working in a team.
Documenting my Sass/.scss files wasn’t my very first idea because this is that part where I’m inclined to work a little bit messy. Nevertheless, it would come handy a lot of times where my codebase started to fall apart or started to be chaotic.
This type of documentation is useful when you work on a bigger project or your framework. In a smaller one, you don’t need it necessarily.
Give your project a solid foundation.
What is SassDoc?
SassDoc is a simple comment based documentation tool like the JSDoc and PHPDoc. You write your doc items (comment blocks) in your code above it in a specified syntax with the predefined annotations. After that, you run the correct command and voila you got a full documentation about your Sass code.
We usually use it for our functions, mixins, variables.
You will not find out, but this is a project of Hugo Giraudel (with Pascal Duez, Valérian Galliat, Fabrice Weinberg) who is the number one Sass guru in the web dev.
Using SassDoc
As I said earlier, using this tool is simple. For a basic usage all you have to do is to install it to your system through npm:
npm install sassdoc -g
and run the default command to your Sass folder
sassdoc <src>
Of course, before that, you need to write some registry!
For a real and complex example check out Viget’s one of these types of documentation!
Simple Example
SassDoc is using a three-slash comment to mark the required comment for itself. If you just want to record a variable without any other explanation you just need to mark with /// like this:
/// $base-font-size: 1.1em;
For a more complex example check out this simple mixin. Here we give a group, set an author, add a parameter, output, and example.
/// Rem output with px fallback.
///
/// @group Typography
/// @author Adam Laki
///
/// @param {Number} $sizeValue - Element's font size
/// @output `font-size` with fallback
///
/// @example scss - Set rem font-size to `.foo`
/// .foo {
/// @include font-size(1.2);
/// }
@mixin font-size($sizeValue: 1) {
font-size: ($sizeValue * 16) * 1px;
font-size: $sizeValue * 1rem;
}
Annotations
In SassDoc there are a lot of annotations which is a custom tag which tells itself what to do with it. There some common annotations like the @description, @param (this is the shorthand of the @property) what we are using more frequently but for a complete list check out the project’s documentation.
Internal Dependency Managment
SassDoc has a handy feature which is automatically managed and list the dependencies of registry item.
/// Blue
$blue: #2196F3;
/// Clearfix
@mixin clearfix() {
content: "";
display: table;
table-layout: fixed;
}
/// Articles footer section styling.
///
/// @group Styling
/// @author Adam Laki
@mixin article-footer() {
@include clearfix();
background: $blue;
color: #fff;
}
In the generated document you can see the “article-footer” issue requires the clearfix[mixin] and the blue[variables]. The usefulness of this is easy to see; it makes more transparent your Sass documentation.
Grouping Items
If you want to make an individual section in your documentation, you can use the @group annotation which creates a new navigation item and separates the content.
Below the groups, there is a subcategory system which is group by type like function, mixin, variable.
/// @group shorthand
Preview Your Color Values
I found this technique when I searched for problems with SassDoc, and I think this is smart!
When you declare your color variables it can handy if you also show that value in some way. With the following snippet you are done:
/// Blue /// <br><img src='data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="5" height="50"><rect fill="#415FD9" x="0" y="0" width="100%" height="100%"/></svg>'> $blue: #2196F3;
As you see above, we use HTML, an inline SVG in an <img> tag. If you generate and check your documentation, you can see the colored rectangle.
For the tip thanks for LukyVJ! Excellent job!
Build Tool Integration
You can use SassDoc with the traditional build tools like Grunt, Gulp or Broccoli. These modules are managed by the core developers. In this article, we use Gulp examples.
var gulp = require('gulp'),
sassdoc = require('sassdoc');
var sassdocOptions = {
dest: './sassdoc',
theme: './node_modules/sassdoc-theme-flippant'
};
gulp.task('sassdoc', function () {
return gulp.src('./sass/**/*.scss')
.pipe(sassdoc(sassdocOptions))
.resume();
});
For more information check out the “Alternative Usages” section in the official documentation.
Build You Own Theme or Use a Good Predefined One
The default theme is a sassy styled one which is good looking but if you need something else you can check some other excellent ones, or you can make your own.
To install another theme, you need to download it and point to the path in the SassDoc config like the following:
npm install sassdoc-theme-flippant --save-dev
var sassdocOptions = {
dest: './sassdoc',
theme: './node_modules/sassdoc-theme-flippant'
};
After this, your next build will be using the new theme.
Convert Your SassDoc to Markdown
It can be handy, and it is not just true for SassDoc but in general for any HTML file.
With the help of Pandoc – which is a universal document converter – you can easily convert your index.html to markdown file with the following command:
pandoc -s index.html -o doc.md --to=markdown_github
Firstly you have to install Pandoc to your system. For more check out the project’s page!
At The End Why Should I Use SassDoc?
In a short answer: because it is a little effort and on a right project it is invaluable.
The learning curve is not a curve, you need maximum one hour to config and learn the basics. You with or without your team can make a lot of profit from this choice so don’t hesitate to make it!
