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.
Then, you will export an annotations array to extend SassDoc.
Each annotation is a function that returns an object with a
name property, a
method, and optionally
methods and well as an
alias array and a
||string||Name of the annotation.|
||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
||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.|
||function||Returns a default value when — if ever — the annotation is not present.|
||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.|
||boolean||Indicates if this annotation is allowed multiple times per item (default is
||array||Array of aliases for the annotation.|
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!
@friend annotation to mark an item as “friend”, for example:
In your templates,
item.friend will be an array of references
to the “friends” items.
For more examples, you can look at the core annotations which are very insightful.