Jump to navigation

There are a number of global configuration options you can set to determine how Fractal handles documentation pages.

Additionally, documentation pages and collections can have their own (optional) configuration files associated with them; or if you prefer pages can specify their configuration in a YAML front-matter section within the page template itself. See the documentation overview for more information.

Global configuration options

These options can be set on your Fractal instance using the fractal.docs.set() method. See the project settings documentation for more details.


Global context data that will be made available to all pages.

fractal.docs.set('default.context', {
    'site-name': 'FooCorp'


Global prefix to apply to all generated handles unless overridden in a collection or page configuration file.

fractal.docs.set('default.prefix', 'foobar'); // default is null


The status to apply to all pages unless overridden in a collection or page configuration file.

fractal.docs.set('default.status', 'wip'); // default is null


The file extension that will be used for all documentation view templates. Note that this must include the leading .

fractal.docs.set('ext', '.html'); // default is '.md'


The default label to be used for index pages.

fractal.docs.set('indexLabel', 'Listing'); // default is 'Overview'


How the collection of documentation pages will be referenced in any navigation.

fractal.docs.set('label', 'Pages'); // default is 'Documentation'


Whether to use Markdown to parse the contents of documentation pages.

fractal.docs.set('markdown', false); // defaults to true

You can also toggle on or off other more fine-grained settings to customise the details of the Markdown parsing:

fractal.docs.set('markdown.smartypants', false);

The default values are:

    gfm: true,
    tables: true,
    breaks: false,
    pedantic: false,
    sanitize: false,
    smartLists: true,
    smartypants: true

See the Marked markdown parser documentation for details on what each option does.


The path to the directory where your documentation pages live.

fractal.docs.set('path', __dirname + '/src/docs');


The set of available statuses that can be assigned to pages. See the statuses documentation for details of the default values and how to override them as required.

fractal.docs.set('statuses', {
    doing: {
        label: "Doing",
        description: "I'm doing it.",
        color: '#F00'
    done: {
        label: "Done",
        description: "I'm done with this.",
        color: "green"


How the collection of documentation pages will be referenced in any titles.

fractal.docs.set('title', 'Pages'); // default is 'Documentation'

Page properties

These are properties that can be specified in an individual page’s YAML front matter section or in a configuration file for that page.


Data to pass to the page when rendering it.

context is an inheritable property. Any context data set on the page will be merged with any context data set upstream in the configuration cascade.

  colors: ['red','pink','blue']


Override the generated handle. Note that this will also have the side effect of preventing any prefixes set in upstream collections being applied to the handle.

handle: my-great-page


Specifies whether the page is hidden (i.e. does not show up in listings or navigation) or not. Overrides the inferred value from an underscore-prefixed file name if set.

hidden: true


The label is typically displayed in any UI navigation items that refer to the page. Defaults to a title-cased version of the page file name if not specified.

label: 'Naming Conventions'


An integer order value, used when sorting pages. Overrides any order value set as a property of the filename if set.

order: 4


The title of a page. Defaults to the same as the label if not specified.

title: 'Amazing Mega Buttons'

Collection properties

Collections can specify properties that should be applied to all child pages of that collection via configuration inheritance. See the documentation on collections for more details on how to work with collections, and for details on available non-inheritable properties like label and title.

The following properties can be set on page collections and will affect the pages within them:


Context data to be made available to (and merged into) all child pages within the collection.

  colors: ['red','pink','blue']


A string to be prefixed on to the generated handles of all pages in that collection.

prefix: 'api'

Given the prefix above, a page with the name of logging that lives within this collection will have the handle @api-logging.


The default status for all pages within the collection.

status: 'wip'