Introduction

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 --config (or -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 .sassdocrc.

sassdoc source/       -c path/to/config.json # Short option and JSON file
sassdoc source/ --config path/to/config.yaml # Long  option and YAML 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 sassdoc function:

var sassdoc = require('sassdoc');
sassdoc(source, config);

Options

Here are the available configuration options that does not depend on the theme whatsoever:

Destination

The 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.

Exclude

A list of patterns to exclude from the sources. It’s like passing negate patterns as <src> but in a more persistent fashion.

exclude:
  - private.scss
  - ./stylesheets/hidden/*

Package

The 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

The 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 /, it’s required as a Node package;
• otherwise it’s required as sassdoc-theme-{{value}} (like sassdoc-theme-unicorn in our example).

Note: see Using Your Own Theme to build your own theme. Also see the Theme Gallery to see some existing themes.

Autofill

The 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:

autofill: []

Or you can enable only some annotations to be autofilled (here all supported annotations are listed):

autofill:
  - throw
  - content
  - require

Groups

The 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. API Helpers).

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.

groups:
  api-helpers: API Helpers
  undefined: Basic API

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 no-update-notifier option.

Note: you can also use the CLI option --no-update-notifier.

Verbose

SassDoc will output messages at the various documentation process states.