Quick tutorial

Lakshan Perera edited this page Jul 1, 2012 · 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 - https://vimeo.com/44990180

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:

     	<body>
     		<header>
     			<h1>{{title}}</h1>
     		</header>
    
     		<div role="main">
     			<img src="{{profile_pic}}" alt="Profile picture"/>
     			<p>{{shortbio}}</p>
     		</div>
     	</body>
  • 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](http://en.wikipedia.org/wiki/Rare_species) 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!