Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jnordberg/wintersmith

A flexible static site generator
https://github.com/jnordberg/wintersmith

nodejs static-site-generator wintersmith

Last synced: 3 days ago
JSON representation

A flexible static site generator

Awesome Lists containing this project

README 

        
#![Wintersmith](http://wintersmith.io/images/wintersmith.svg)



Wintersmith is a simple yet flexible static site generator. It takes contents (markdown, less, scripts, etc), transforms them using plugins and outputs a static website (html, css, images, etc) that you can host anywhere.



It ships with plugins for [markdown](http://daringfireball.net/projects/markdown/) and [pug templates](https://github.com/pugjs/pug), if you need something else check the [plugin listing][plugin-listing] or [write your own][plugin-guide]!



## Resources



 * [Project site][website]

 * [API Documentation][docs]

 * [Wiki][wiki]

 * [stackoverflow tag](http://stackoverflow.com/questions/tagged/wintersmith)

 * IRC - **#wintersmith** on freenode



[website]: http://wintersmith.io "Wintersmith project website"

[docs]: http://wintersmith.io/docs "Wintersmith API Documentation"

[wiki]: https://github.com/jnordberg/wintersmith/wiki "Wintersmith wiki"

[plugin-listing]: https://github.com/jnordberg/wintersmith/wiki/Plugins "Wintersmith plugin listing"

[plugin-guide]: https://github.com/jnordberg/wintersmith/wiki/Writing-plugins "Wintersmith plugin guide"



## Quick-start



First install wintersmith using [npm](http://npmjs.org/):



```bash

$ npm install wintersmith -g

```



This will install wintersmith globally on your system so that you can access the `wintersmith` command from anywhere. Once that is complete run:



```bash

$ wintersmith new 

```



Where `` is the location you want the site to be generated. This creates a skeleton site with a basic set of templates and some articles, while not strictly needed it's a good starting point.



Now enter the directory and start the preview server:



```bash

$ cd 

$ wintersmith preview

```



At this point you are ready to start customizing your site. Point your browser to `http://localhost:8080` and start editing templates and articles.



When done run:



```bash

$ wintersmith build

```



This generates your site and places it in the `build/` directory - all ready to be copied to your web server!



And remember to give the old `--help` a look :-)



## Overview



A wintersmith site is built up of three main components: contents, views and templates.



Contents is a directory where all the sites raw material goes (markdown files, images, javascript etc). This directory is then scanned to produce what's internally called a ContentTree.



The ContentTree is a nested object built up of ContentPlugins and looks something like this:



```javascript

{

  "myfile.md": {MarkdownPlugin} // plugin instance, subclass of ContentPlugin

  "some-dir/": { // another ContentTree instance

    "image.jpg": {StaticPlugin}

    "random.file": {StaticPlugin}

  }

}

```



![Wintersmith](http://wintersmith.io/images/flow.svg)



This content tree is provided in full to the views when rendering. This gives you a lot of flexibility when writing plugins, you could for example write a plugin that generates a mosaic using images located in a specific directory.



Wintersmith comes with a default Page plugin that renders markdown content using templates. This plugin takes markdown (combined with some metadata, more on this later) compiles it and provides it to a template along with the content tree and some utility functions.



This brings us to the second component, the template directory. All templates found in this directory are loaded and are also passed to the content plugins when rendering.



By default only `.pug` templates are loaded, but you can easily add template plugins to use a template engine of your choosing.



Check the `examples/` directory for some inspiration on how you can use wintersmith or the [showcase](https://github.com/jnordberg/wintersmith/wiki/Showcase) to see what others are doing.



## Configuration



Configuration can be done with command-line options, a config file or both. The config file will be looked for as `config.json` in the root of your site (you can set a custom path using `--config`).



### Options



Name         | Default         | Description

-------------|-----------------|-----------------------------------------------

contents     | `./contents`    | contents directory location

templates    | `./templates`   | templates directory location

views        | `null`          | views directory location, optional

locals       | `{}`            | global site variables, can also be a path to a json file

require      | `{}`            | modules to load and add to locals. e.g. if you want underscore as `_` you would say `{"_": "underscore"}`

plugins      | `[]`            | list of plugins to load

ignore       | `[]`            | list of files or pattern to ignore

output       | `./build`       | output directory, this is where the generated site is output when building

filenameTemplate | `:file.html`| outputs filenames and paths according to a template. ([documentation](https://github.com/jnordberg/wintersmith/wiki/Page-Plugin#filename-templating))

introCutoffs | `['



  class SimonSays extends env.ContentPlugin



    constructor: (@filepath, text) ->

      @text = "Simon says: #{ text }"



    getFilename: -> @filepath.relative # relative to content directory



    getView: -> (env, locals, contents, templates, callback) ->

      callback null, new Buffer @text



  SimonSays.fromFile = (filepath, callback) ->

    fs.readFile filepath.full, (error, buffer) ->

      if error

        callback error

      else

        callback null, new SimonSays filepath, buffer.toString()



  env.registerContentPlugin 'text', '**/*.txt', SimonSays

  callback() # tell the plugin manager we are done

```



See the [plugin guide][plugin-guide] for more info.



## Using wintersmith programmatically



example:



```javascript



var wintersmith = require('wintersmith');



// create the sites environment, can also be called with a config object. e.g.

// {contents: '/some/contents', locals: {powerLevel: 10}}, ..}

var env = wintersmith('/path/to/my/config.json');



// build site

env.build(function(error) {

  if (error) throw error;

  console.log('Done!');

});



// preview

env.preview(function(error, server) {

  if (error) throw error;

  console.log('Server running!');

});



// do something with the content tree

env.load(function(error, result) {

  if (error) throw error;

  console.log('Contents loaded!');

});



```



Check the source or [api docs][docs] for a full list of methods.



## Contributing



To run a development that compiles the coffee script files on the fly use the `./bin/dev/cli` command. The chdir `-C ` flag is handy for pointing it to a test project to experiment with.



## About



Wintersmith is written by [Johan Nordberg](http://johan-nordberg.com) using [CoffeeScript](http://coffeescript.org/) and licensed under the [MIT-license](http://en.wikipedia.org/wiki/MIT_License).



The name is a nod to [blacksmith](https://github.com/flatiron/blacksmith) which inspired this project.