Punch is a simple tool to generate a static website out of Mustache templates and content stored in either JSON or Markdown format.
- Simple templating.
- Flexible content structure.
- Supports client-side rendering.
- Can be used with your favorite editor, SCM or host.
- App Promo sites
- Portfolio sites
- Project Documentation
- Event Marketing sites
- or even for your cat's homepage...
Remember: Punch is not a blogging engine
(You can use Jekyll and other similar tools to power a blog)
-
Download and Install Node.js. http://nodejs.org/#download
-
Install
npm-curl http://npmjs.org/install.sh | sh -
Finally, run
npm install punch
Watch the Screencast - http://vimeo.com/40645795
Read the introductory blog post - http://laktek.com/2012/04/19/punch-a-fun-and-easy-way-to-build-modern-websites/
Here's a step by step guide on how to create a simple HTML site using Punch.
-
First of all we should create a new directory for our site. (
mkdir awesome_site) -
Then, go inside the directory (
cd awesome_site) and run the commandpunch setup. -
This will create two directories to hold
templatesandcontents. Also, it will add aconfig.jsonfile which contains the default configuration for Punch. -
Say we want to have a page called
about.html, to give an overview of the company and details of the team members. -
First we must create a corresponding template for the page inside
templatesdirectory. -
Here's how our
about.mustachetemplate will look like.```mustache <!doctype html> <head> <meta charset="utf-8"> <title>{{title}}</title> </head> <body> <h1>{{title}}</h1> <p>{{{overview}}}</p> <ul> {{#team}} <li><strong>{{name}} - {{bio}}</li> {{/team}} <ul> </body> </html> ``` -
Now inside
contentsdirectory let's create a file calledabout.jsonto hold the corresponding content. -
We'll add the following content in
about.json.```json { "title": "About Us", "team": [ { "name": "Pointy-Haired Boss", "bio": "Incompetent Manager" }, { "name": "Wally", "bio": "Senior Engineer" }, { "name": "Dilbert", "bio": "Engineer" } ] } ``` -
We also have a lengthy company overview written in markdwon format. Instead of adding it to the
about.jsonfile, we'll be keeping it seperately. For that we create a new directory namedaboutinside thecontentsdirectory and save the markdown file there asoverview.markdown. -
Now we can generate the site, for that go back to the top-most directory (
cd ../) and run the commandpunch. -
Punch will output the generated pages in a directory named
public. -
To view the generated site you can run the command
python -m SimpleHTTPServerinside thepublicdirectory. -
Then point your browser to
http://localhost:8000/about.htmlto see the generated about page.
Partial templates
You can specify reusable partial templates with Punch. Partial templates should be named with a leading underscore character (eg. _sidebar.mustache). To render a partial in another template, do this:
{{> sidebar }}
Shared content
If you create a JSON file with the name shared.json or a directory named shared under contents its content will be automatically available for all templates in your site.
Client-side Rendering
It's possible to use the Punch's renderer in the browser as well. All you need to do is include the latest mustache.js and the Punch's renderer in your client-side script.
```html
<script type="text/javascript" src="assets/mustache.js"></script>
<script type="text/javascript" src="node_modules/punch/lib/renderers/mustache.js"></script>
```
Here's how you can use it in the browser:
```javascript
var renderer = new MustacheRenderer();
renderer.afterRender = function(output){
document.getElementById("client_block").innerHTML = output;
};
renderer.setTemplate('<p>{{content}}</p>');
renderer.setContent({"content": "test"});
renderer.setPartials({});
```
Since Punch's renderer is asynchronous, you can call setTemplate, setContent and setPartials once you have the data (eg. after loading via AJAX). Rendering will happen when the renderer receives all 3 method calls.
Configuration options
```json
{
"template_dir": "templates", // directory to look for templates
"content_dir": "contents", // directory to look for contents
"output_dir": "public", // directory to save the generated output
"output_extension": "html", // default extension to use for output files
"shared_content": "shared", // name of the file/directory of shared content inside `contents`
// register new renderers or parsers (paths should be valid node.js require paths)
"renderers": {
"mustache": "./renderers/mustache"
},
"parsers": {
"markdown": "./parsers/markdown"
}
};
```
There's a sample available in /sample, which will help you to understand the directory structure and configurations.
You are encouraged to contribute and be part of Punch:
- Report any bugs or feature requests - http://github.com/laktek/punch/issues/
- Help with improving the documentation, site and screencasts.
- Fork, Refactor and send pull requests.
- If you have big ideas for Punch, please feel free to contact me (Lakshan - http://laktek.com/about). Let's have a chat.