Fractal

# fractal.docs

The .docs property on the main fractal instance provides access to the documentation source object.

const fractal = require('@frctl/fractal').create();
fractal.docs.set('ext', '.html'); // set a configuration property on the documentation source object.

TIP

The fractal.docs object is a Collection and so inherits all the methods that are available on Collection instances in addition to those documented below. See the Collection documentation for full details.

# Methods

# .set(path, value)

  • path - String
  • value - String | Object

Set the value of a configuration setting, identified by its path. See the docs configuration documentation for details of available options.

fractal.docs.set('ext', '.html');

# .get(path)

  • path - String

Get the value of a configuration setting, identified by it's path. For a complete list of configuration values see the docs configuration documentation.

console.log(fractal.docs.get('ext')); // '.html'

# .engine(adapter)

  • adapter - Adapter | String

Set the template engine adapter to be used for rendering the component view templates.

fractal.docs.engine('@frctl/nunjucks'); // no customisation needed, pass string of module name

const nunjucks = require('@frctl/nunjucks')({
    // set config here
});
fractal.docs.engine(nunjucks); // or pass in configured Adapter instance

# .resolve(context)

  • context - Object

Resolve the supplied context object. Parses out and resolved @handle syntax data references and any promises contained in the data. Returns a Promise.

const resolvedContext = fractal.components.resolve({
    title: '@styleguide.title',
    text: 'Some text',
    entries: someFunctionThatReturnsAPromise()
});

# .on(event, callback)

  • event - String
  • callback - Function

Listen out and respond to lifecycle events. See the Events section for more details.

fractal.docs.on('changed', function(eventData){
	console.log(`Change in component directory detected`);
});

# .load()

Perform an initial read and parse of the docs directory. Returns a Promise.

fractal.docs.load().then(() => {
	console.log('Finished parsing docs directory!');
});

# .watch()

Start a watch task to monitor the docs directory for changes.

fractal.docs.watch();

# .unwatch()

Stop any currently running watch tasks.

fractal.docs.unwatch();

# Properties

# .label

The text used to reference the docs source in any navigation.

# .title

The text used to reference the docs source in any titles.

# .isLoaded

Boolean, true if the initial source directory read and parse has been completed.

# .fullPath

Full, resolved filesystem path to the docs directory.

# Events

The fractal.docs object is an EventEmitter and emits events that can be listened to via using the .on() method (documented above). Available events to listen for are described below:

# loaded

Emitted when Fractal has finished the initial parse of the docs directory.

fractal.docs.on('loaded', function(){
	console.log(`Docs directory has been loaded`);
});

# changed

Emitted when one or more files in the docs directory are added, removed or edited, but before Fractal has re-parsed the contents of the directory.

fractal.docs.on('changed', function(eventData){
	console.log(`Change in docs directory`);
});
  • eventData - an event data object, e.g. { event: 'change', path: 'path/to/file.scss' }

# updated

Emitted when Fractal has finished re-parsing the docs directory after a change.

fractal.docs.on('updated', function(source, eventData){
	console.log(`Docs source has been updated`);
});
  • eventData - an event data object, e.g. { event: 'change', path: 'path/to/file.scss' }

← fractal.web →