Code Monkey home page Code Monkey logo

wintersmith's Introduction

#Wintersmith

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 and jade templates, if you need something else check the plugin listing or write your own!

Resources

Quick-start

First install wintersmith using npm:

$ 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:

$ wintersmith new <path>

Where <path> 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:

$ cd <path>
$ 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:

$ 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:

{
  "myfile.md": {MarkdownPlugin} // plugin instance, subclass of ContentPlugin
  "some-dir/": { // another ContentTree instance
    "image.jpg": {StaticPlugin}
    "random.file": {StaticPlugin}
  }
}

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 .jade 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 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
baseUrl / base url that site lives on, e.g. /blog/.
hostname null hostname to bind preview server to, null = INADDR_ANY
port 8080 port preview server listens on

All paths can either be relative or absolute. Relative paths will be resolved from the working directory or --chdir if set.

The Page plugin

A Page is either a markdown file with metadata on top or a json file located in the contents directory.

---
title: My first post
date: 2012-12-12 12:12
author: John Hjort <[email protected]>
template: article.jade
----

# Hello friends!

Life is wonderful, isn't it?

or use json to simply pass metadata to a template:

{
  "template": "template.jade",
  "stuff": {
  	"things": 123,
  	"moar": [1, 2, 3]
  }
}

Pages will be rendered as html, so for example index.md would be rendered to index.html and some-dir/data.json to some-dir/data.html.

All relative links in the markdown will be resolved correctly when rendering. This means you can just place image.png in the same directory and simply include it in your markdown as ![my image](image.png)

This is especially convenient when using a markdown editor (read Mou if you're on a mac).

Metadata

Metadata is parsed using js-yaml and will be accessible in the template as page.metadata.

There are two special metadata keys, The first one is template which specifies what template to render the page with. If the key is omitted or set to none the page will not be rendered (but still available in the content tree).

The second one is filename which can be used to override the output filename of the page. Useful if you need to output a .xml file or something similar.

Templates

When a page is rendered to a template the page instance is available as page in the template context. The content tree is also available as contents and config.locals is the root object.

The Page model

The Page model (inherits from ContentPlugin)

Properties:

Name Description
metadata object containing the pages metadata
title metadata.title or Untitled
date Date object created from metadata.date if set, unix epoch time if not
rfc822date a rfc-822 formatted string made from date
body markdown source
html parsed markdown as html

Plugins

A plugin is a function that's called with the wintersmith environment and a callback.

Plugins are loaded by adding a "require id" to config.plugins. This can be a path, local- or global module. It works just like you would expect a require() call to.

Plugin example:

fs = require 'fs'

module.exports = (env, callback) ->

  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 for more info.

Using wintersmith programmatically

example:

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 for a full list of methods.

About

Wintersmith is written by Johan Nordberg using CoffeeScript and licensed under the MIT-license.

The name is a nod to blacksmith which inspired this project.

wintersmith's People

Contributors

alexnormand avatar benjie avatar daddye avatar daiz avatar dashed avatar hamoid avatar hindol avatar iammerrick avatar jnordberg avatar lhagan avatar petrhosek avatar smebberson avatar tlvince avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.