Permalink
Browse files

Document new stuff and add a license file

  • Loading branch information...
1 parent 6f46a5b commit 92f177a5cdb6a5a915c71cbb6bbfb611a73d3290 @jnordberg committed May 22, 2013
Showing with 65 additions and 144 deletions.
  1. +21 −0 LICENSE.md
  2. +44 −144 README.md
View
@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright (c) 2012-2013 Johan Nordberg - http://johan-nordberg.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+__THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.__
View
@@ -12,7 +12,7 @@ It ships with plugins for [markdown](http://daringfireball.net/projects/markdown
* **#wintersmith** on freenode
[website]: http://jnordberg.github.io/wintersmith "Wintersmith project website"
-[docs]: http://jnordberg.github.io/wintersmith/docs "Wintersmith documentation"
+[docs]: http://jnordberg.github.io/wintersmith/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]: #TODO "Wintersmith plugin guide"
@@ -80,7 +80,7 @@ By default only `.jade` templates are loaded, but you can easily add template pl
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.
-## Config
+## 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`).
@@ -104,7 +104,7 @@ All paths can either be relative or absolute. Relative paths will be resolved fr
## The Page plugin
-A page is either a markdown file with metadata on top or a json file located in the contents directory.
+A Page is either a markdown file with metadata on top or a json file located in the contents directory.
```markdown
---
@@ -125,9 +125,9 @@ or use json to simply pass metadata to a template:
```json
{
"template": "template.jade",
- "meta": {
- "greta": 123,
- "peta": [1, 2, 3]
+ "stuff": {
+ "things": 123,
+ "moar": [1, 2, 3]
}
}
```
@@ -150,137 +150,59 @@ The second one is `filename` which can be used to override the output filename o
### 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 the config.locals object as `locals`.
-
-[underscore.js](http://documentcloud.github.com/underscore/) is also available as `_` to provide some utility to aid you sorting and filtering the content tree.
+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:
-<table>
- <tr>
- <td>metadata</td>
- <td>the metadata object</td>
- </tr>
- <tr>
- <td>title</td>
- <td>`metadata.title` or `Untitled`</td>
- </tr>
- <tr>
- <td>date</td>
- <td>Date object from `metadata.date` if set or unix epoch time</td>
- </tr>
- <tr>
- <td>rfc822date</td>
- <td>a rfc-822 formatted string made from `date`</td>
- </tr>
- <tr>
- <td>body</td>
- <td>unparsed markdown content</td>
- </tr>
- <tr>
- <td>html</td>
- <td>parsed markdown content</td>
- </tr>
-</table>
-
-## Writing plugins
-
-Wintersmith has two types of plugins, content plugins that transform contents and template plugins that are provided to the content plugins to help render contents.
-
-A list of 3rd party plugins can be found on [the wiki](https://github.com/jnordberg/wintersmith/wiki/Plugins).
-
-
-### Content Plugins
-
-A content plugin is a subclass of `ContentPlugin` and should provide a `fromFile` class method, a `render` instance method and a `getFilename` instance method.
-
-`render` is called with the content tree, template list, locals and a callback. Have a look in `src/contents.coffee` it's pretty well documented.
-
-Content plugins are registered using the `registerContentPlugin` function.
-
-<table>
- <tr>
- <th colspan=2>registerContentPlugin(group, pattern, plugin)</th>
- </tr>
- <tr>
- <td>group</td>
- <td>
- <p><em>string</em> - plugin group name
-
- <p>Groups are used to easily access a specific type of content in the tree. The content tree has a special property <code>_</code> that returns a object with all plugin groups as <code>{groupname: [pluginInstance, ..], ..}</code>
-
- <p>For example you can use <code>contents.somedir._.pages</code> to get an array of all pages in a directory.
- </td>
- </tr>
- <tr>
- <td>pattern</td>
- <td>
- <p><em>string</em> - glob pattern (e.g. <code>**/*.txt</code>)
-
- <p>Glob pattern used to match files that should be handled by the plugin. Uses the [minimatch](https://github.com/isaacs/minimatch) module.
- </td>
- </tr>
- <tr>
- <td>plugin</td>
- <td>
- <p><em>class</em> - the ContentPlugin subclass
- </td>
- </tr>
-</table>
-
-
-### Template Plugins
-
-A template plugins is a subclass of `TemplatePlugin` and should also provide a `fromFile` class method and a `render` instance method.
+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
-Template plugins are registered using:
+## Plugins
-`function registerTemplatePlugin(pattern, plugin) { .. }`
+A plugin is a function that's called with the wintersmith environment and a callback.
-where *pattern* is the glob pattern to match in the template directory and plugin is the plugin subclass.
+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 Modules
-
-The easiest way to load a wintersmith plugin is to use the `plugins` config option.
-
-Example:
-
-`myplugin.coffee`
+Plugin example:
```coffeescript
+fs = require 'fs'
-module.exports = (wintersmith, callback) ->
+module.exports = (env, callback) ->
- class TextPlugin extends wintersmith.ContentPlugin
+ class SimonSays extends env.ContentPlugin
- constructor: (@_filename, @_text) ->
+ constructor: (@filepath, text) ->
+ @text = "Simon says: #{ text }"
- getFilename: ->
- @_filename
+ getFilename: -> @filepath.relative # relative to content directory
- render: (locals, contents, templates, callback) ->
- # do something with the text!
- callback null, new Buffer @_text
+ getView: -> (env, locals, contents, templates, callback) ->
+ callback null, new Buffer @text
- TextPlugin.fromFile = (filename, base, callback) ->
- fs.readFile path.join(base, filename), (error, buffer) ->
+ SimonSays.fromFile = (filepath, callback) ->
+ fs.readFile filepath.full, (error, buffer) ->
if error
callback error
else
- callback null, new TextPlugin filename, buffer.toString()
+ callback null, new SimonSays filepath, buffer.toString()
- wintersmith.registerContentPlugin 'text', '**/*.txt', TextPlugin
+ env.registerContentPlugin 'text', '**/*.txt', SimonSays
callback() # tell the plugin manager we are done
-
```
-To use this plugin simply pass the path to the file to the cli tool (`--plugins ./myplugin.coffee`)
-
-You can also use globally or locally installed modules as plugins.
+See the [plugin guide][plugin-guide] for more info.
## Using wintersmith programmatically
@@ -290,47 +212,25 @@ example:
var wintersmith = require('wintersmith');
-var options = {
- 'output': '/var/www/pub',
- 'contents': '/foo/contents',
- 'contents': '/foo/templates',
- 'plugins': ['some-plugin'],
- 'locals': {foo: 'bar'}
-};
-
-wintersmith(options, callback(error) {
- if (error) {
- throw error;
- } else {
- console.log('great success!');
- }
-});
+wintersmith('/path/to/my/config.json', callback(error, env) {
+ if (error) throw error;
+
+ // build site
+ env.build(function(error) { // .. });
+
+ // preview
+ env.preview(function(error, server) { // preview server now running });
-// you can also use the api to get the content tree
-wintersmith.loadContents('path/to/contents', callback(error, contents) {
// do something with the content tree
+ env.load(function(error, result) { // .. });
});
```
-There are more API methods defined, have a look at the source it's pretty well-commented.
+Check the source or [api docs][docs] for a full list of methods.
## 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 (and [Terry Pratchett](http://www.terrypratchett.co.uk/) of course).
-
-Some of the great node.js modules that wintersmith uses:
-
- * [async](https://github.com/caolan/async)
- * [marked](https://github.com/chjj/marked)
- * [jade](https://github.com/visionmedia/jade)
- * [coffee-script](https://github.com/jashkenas/coffee-script)
-
-Check the `package.json` for a complete list.
-
-
-----
-
-*© 2012 FFFF00 Agents AB*
+The name is a nod to [blacksmith](https://github.com/flatiron/blacksmith) which inspired this project.

0 comments on commit 92f177a

Please sign in to comment.