Extending SassDoc

Introduction

SassDoc allows you to define custom annotations. This can only be done from a custom theme since there is no way for SassDoc to guess what to do or how those annotations should be displayed.

Here’s a simple example to add a few simple annotations to SassDoc within your theme. First, you’ll have the usual theme function. Refer to Using Your Own Theme for more informations about this.

module.exports = function () {
  // Usual theme function
};

Then, you will export an annotations array to extend SassDoc.

module.exports.annotations = [];

Schema

Each annotation is a function that returns an object with a name property, a parse method, and optionally resolve, default and autofill methods and well as an alias array and a multiple boolean.

Key	Type	Description
`name`	string	Name of the annotation.
`parse`	function	Takes the annotation content as parameter and returns the parsed data (can be of any type — it will be available in the theme as `item.<annotationName>`, as an array if `multiple` is `true`).
`resolve`	function	Called after the raw data is generated, where the whole SassDoc data is being passed (indexed by type and name). You can then modify this object reference as you want to complete your data structure while having access to the whole data.
`default`	function	Returns a default value when — if ever — the annotation is not present.
`autofill`	function	Takes a parsed annotation object. You can modify this object reference as you want while having access to the whole parsed content of the current annotation.
`multiple`	boolean	Indicates if this annotation is allowed multiple times per item (default is `true`).
`alias`	array	Array of aliases for the annotation.

Examples

We can add an @awesome annotation (meaning the annotated item is awesome) (also aliased as @wow). This annotation is just meant to be applied as-is, without any argument. You can then add a condition on item.awesome in your templates!

module.exports.annotations.push(function () {
  return {
    name: 'awesome',
    parse: function () { return true; },
    default: function (comment) { return false; },
    autofill: function (comment) {},
    multiple: false,
    alias: ['wow']
  };
});

Then, a @friend annotation to mark an item as “friend”, for example:

/// @friend {function} foo
/// @friend {variable} bar

In your templates, item.friend will be an array of references to the “friends” items.

module.exports.annotations.push(function () {
  return  {
    name: 'friend',
    parse: function (text) {
      var match = /^\{(.*)\}\s*(.*)$/.exec(text.trim());
      return {
        type: match[1],
        name: match[2],
      };
    },
    resolve: function (data) {
      Object.keys(data).forEach(function (type) {
        Object.keys(data[type]).forEach(function (name) {
          var item = data[type][name];

          if (!item.friend) {
            return;
          }

          item.friend.map(function (friend) {
            return data[friend.type][friend.name];
          });
        });
      });
    }
  };
});

For more examples, you can look at the core annotations which are very insightful.

Extending SassDoc

Getting started

Custom theme

Alternative usages

Extras

Introduction

Schema

Examples