Wintersmith API Documentation


The configuration object

Instance Methods


Class Methods

fromFile(path, callback)

Read config from path as JSON and callback with a Config instance.


Read config from path as JSON return a Config instance.


The mother of all plugins

Instance Methods


Return a view that renders the plugin. Either a string naming a exisitng view or a function: (env, locals, contents, templates, callback) -> Where environment is the current wintersmith environment, contents is the content-tree and templates is a map of all templates as: {filename: templateInstance}. callback should be called with a stream/buffer or null if this plugin instance should not be rendered.


Return filename for this content. This is where the result of the plugin's view will be written to.


Return url for this content relative to base.


Return vanity color used to identify the plugin when printing the content tree choices are: bold, italic, underline, inverse, yellow, cyan, white, magenta, green, red, grey, blue, rainbow, zebra or none.


Return plugin information. Also displayed in the content tree printout.

Class Methods

property(name, getter)

Define read-only property with name.

fromFile(filepath, callback)

Calls callback with an instance of class. Where filepath is an object containing both the absolute and realative paths for the file. e.g. {full: "/home/foo/mysite/contents/somedir/somefile.ext", relative: "somedir/somefile.ext"}


Static file handler, simply serves content as-is. Last in chain.

Instance Methods





Class Methods

fromFile(filepath, callback)


The Wintersmith environment.

Instance Methods

constructor(config, @workDir, @logger)

Create a new Environment, config is a Config instance, workDir is the working directory and logger is a log instance implementing methods for error, warn, verbose and silly loglevels.


Reset environment and clear any loaded modules from require.cache



Resolve locals and loads any required modules.


Resolve pathname in working directory, returns an absolute path.


Resolve pathname in contents directory, returns an absolute path.


Resolve module to an absolute path, mimicing the node.js module loading system.


Resolve path relative to working directory.


Resolve path relative to contents directory.

registerContentPlugin(group, pattern, plugin)

Add a content plugin to the environment. Files in the contents directory matching the glob pattern will be instanciated using the plugin's fromFile factory method. The group argument is used to group the loaded instances under each directory. I.e. plugin instances with the group 'textFiles' can be found in contents.somedir._.textFiles.

registerTemplatePlugin(pattern, plugin)

Add a template plugin to the environment. All files in the template directory matching the glob pattern will be passed to the plugin's fromFile classmethod.

registerGenerator(group, generator)

Add a generator to the environment. The generator function is called with the env and the current content tree. It should return a object with nested ContentPlugin instances. These will be merged into the final content tree.

registerView(name, view)

Add a view to the environment.


Return an array of all registered content groups

loadModule(module, unloadOnReset)

Requires and returns module, resolved from the current working directory.

loadPluginModule(module, callback)

Load a plugin module. Calls callback when plugin is done loading, or an error ocurred.

loadViewModule(id, callback)

Load a view module and add it to the environment.


Loads any plugin found in @config.plugins.


Loads files found in the @config.views directory and registers them as views.


Build the ContentTree from @contentsPath, also runs any registered generators.


Load templates.


Returns locals.


Convenience method to load plugins, views, contents, templates and locals.


Start the preview server. Calls callback with the server instance when it is up and running or if an error occurs. NOTE: The returned server instance will be invalid if the config file changes and the server is restarted because of it. As a temporary workaround you can set the _restartOnConfChange key in settings to false.

build(outputDir, callback)

Build the content tree and render it to outputDir.

Class Methods

create(config, workDir, log)

Set up a new environment using the default logger, config can be either a config object, a Config instance or a path to a config file.


Winston transport that logs info to stdout and errors stderr

Instance Methods


log(level, msg, meta, callback)


A template plugin subclass have to implement a render instance method and a fromFile class method.

Instance Methods

render(locals, callback)

Render template using locals and callback with a ReadStream or Buffer containing the result.

Class Methods

fromFile(filepath, callback)

callback with a instance of created from filepath. Where filepath is an object containing the full and relative (to templates directory) path to the file.