SassDoc comes with surprisingly few configuration in itself. Most of the configuration is brought by the theme. However, you don’t have to set up a configuration file in the theme package, that would be silly.
Here is how it works: SassDoc merges the configuration file you provide (or that is being automatically fetched) with the one from the theme. If an option is set in both files, the one you set yourself overrides the one from the theme.
To provide a configuration file, use the
-c) option when running
sassdoc. If the option is not defined, SassDoc will try to find a file named
.sassdocrc (no extension). So if you don’t feel like passing the
--config option every time, just name your file
If you are using the Node API rather than the CLI tool, you can pass your configuration object as the second argument of the
Here are the available configuration options that does not depend on the theme whatsoever:
||String / Object||
dest option is the path to the documentation directory generated by SassDoc. By default, it is
sassdoc, in the current directory.
Caution! SassDoc will wipe this directory at every run, so do not put anything worthwhile in it.
A list of patterns to exclude from the sources. It’s like passing negate patterns as
<src> but in a more persistent fashion.
package option is either a path (string) to a JSON file or directly an object.
It contains information about the documented project (for instance a
package.json, hence the name of the key).
If you provide a path, it will be resolved from the configuration file (or CWD if you have no configuration file). By default, it’s
package.json (with the same resolving rules).
Note: a given path must be relative to the configuration file.
If this doesn’t work for you, then you can set your own package. The package object (either direct or required from a path) should ideally contain (for the theme to access to various information about your project):
title: human name of your project
name: package name of your project
version: your project’s version
license: your project’s license
homepage: URL to your project’s homepage
description: description of your project
Note: if you set this option as a path, it will be overriden with the content of the mentioned JSON file once in the view, thus
package will no longer contain a string, but an object.
theme option is the name of a theme to be used. If not set, it will default to
default, which means SassDoc will use
sassdoc-theme-default, the official theme.
Based on the value you set, for instance
unicorn, SassDoc will try to resolve it this way:
- if the value contains a
required as a Node package;
- otherwise it’s required as
sassdoc-theme-unicornin our example).
autofill option tells which annotations SassDoc should try to autofill when possible. For instance, SassDoc is able to figure from your code if an item requires another item, or if an item is likely to throw an error (
@error directive from Sass) in some circumstances.
Meanwhile, SassDoc is not a Sass lexer. It is not infallible, and in some rare occasions, it can return some false positive annotations. To prevent this from happening, either you’re able to locate the issue and fix it, or you can disable the autofilling for this specific type of annotation by removing its name from the array.
For instance, a falsy value, like an empty array would disable SassDoc autofill feature altogether:
Or you can enable only some annotations to be autofilled (here all supported annotations are listed):
groups option is an object of aliases for group slugs. When you gather items in groups with the
@group annotation, you specify a slug string, without spaces or formatting (e.g.
api-helpers). In the
groups object, you can associate a group slug with a group name so the latter gets used in the view rather than the dirty slug (e.g.
All non-grouped items are gathered by SassDoc in an
undefined group, that is being aliased as General as a default. Feel free to change this to suit your preferences.
Note: that for this feature to work, sassdoc-extras has to be used by the theme, which is obviously the case with the default theme.
No update notifier
SassDoc tries to make sure you always use an up-to-date version. If it is not the case, it will prompt you to update your current version. You can disable this behaviour by using the
Note: you can also use the CLI option
SassDoc will output messages at the various documentation process states.