Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Quick tutorial

Lakshan Perera edited this page · 11 revisions

This tutorial will show how to create a simple HTML site with Punch, preview it and then publish it to the web.

You can watch this tutorial as a screencast from here -

Site we are creating is a tribute for Lonesome George.

  • First of all, let's create the structure for new site by running punch setup george.

    This will create a new directory named george in your current path. Inside this directory you will find two directories named templates and contents. Also, there is a file called config.json, which holds the default configurations for the site.

  • Then we need to create the templates for the site. I prefer using HTML5 boilerplate as a scaffold for site's templates, so I download and extract its stripped version.

  • We can rename index.html to index.mustache to create the template file for index page. Mustache is a template format Punch can render.

    This is how the body of index page template will look like:

            <div role="main">
                <img src="{{profile_pic}}" alt="Profile picture"/>
  • Now, we need to create the corresponding content that's needed to render the template. For this, we are creating a file called index.json inside contents directory.

  • In the index.json, lets add the title and path for profile picture:

        "title": "Lonesome George",
        "profile_pic": "img/profile_pic.png"
  • We also, need to give a value for shortbio. Unlike the previous values, this would be a paragraph and needs to be formatted. So rather than defining it as a JSON value, I prefer to format it using Markdown.

    Keep in mind, if you create a directory inside contents with the same name as a content file; Punch will also parse the contents in that directory and append them to the content file.

    So we are can create a directory named index. and inside it creating a file called shortbio.markdown. The following content will go in shortbio.markdown:

    The **last known individual** of the subspecies was a male named _Lonesome George_, who died on 24 June 2012. In his last years, he was known as the [rarest creature]( in the world. George served as a potent symbol for conservation efforts in the Galápagos and internationally.
  • Let's preview what we did so far in the browser. For that, we need to start Punch's development server by running punch s. This will create a new server on port 9009.

    Point the browser to http://localhost:9009 to see the rendered index page.

  • You can continue to add more content, tweak the templates and immediately see the changes by refreshing the browser.

  • The generated output is stored in public directory under your site directory.

  • Finally, we are going to publish the site we just created. We are going to use Amazon S3 to host our site.

    You will need to create a new bucket to host the site and a user with permissions to access the bucket.

    Add those credentials in the config.json file, under publish:

    "publish"       : {
    "s3"          : {
      "key"       : "auth-key"
    , "secret"    : "secret"
    , "bucket"    : "bucket-name"

    Then, run punch p to publish the generated site to S3.

  • Viola! Now the site is live!

Something went wrong with that request. Please try again.