May 13, 2012

Chisel

(I write this for my twelve year old daughter, who is interested in running her own personal web log on Mac OS X.)

setup and run

Python 2.7.x, the required scripting language to run Chisel, comes pre-installed on a Mac OS X, and so you’re ready to dive straight into the following steps. (Use Terminal1 to run commands in steps below.)

  1. Install python package management system, pip.

    sudo easy_install pip
    
  2. Install Markdown (a plain-text to html marking language) and Jinja2 (a template engine in python):

    sudo pip install markdown jinja2
    
  3. Save your copy of chisel under ~/Sites folder. Edit chisel.py and update the settings as below:

    SOURCE = os.environ["HOME"] + "/Sites/www/posts/"
    DESTINATION = os.environ["HOME"] + "/Sites/www/"
    TEMPLATE_PATH = os.environ["HOME"] + "/Sites/chisel/templates/"
    HOME_SHOW = 3
    URLEXT = ".html"
    
  4. With mkdir -p ~/Sites/www/posts ~/Sites/www/images, create a site structure that looks like below:

    ~/Sites
        |
        +-- www
        |    |
        |    +-- posts
        |    |
        |    +-- images
        |
        +-- chisel
    
  5. Write posts in Markdown and park them in the sub-folder posts , e.g., my-first-post.md. (Separate words with a hyphen in file names in posts, images, files; avoid using spaces or other special characters — they are unfriendly to URLs.)

  6. Post pre-format: All posts require a minimum pre-formatted information for posts to be parsed into their HTML equivalents by Chisel. Following is the structure of a typical post:

    My first post
    12/24/2012
    
    Blah blah..
    
    Blah blah, blah..
    

    Line 1 is the title of the post. On line 2, the date follows the format of month/day/year. Line 3 be blank. Line 4 onward, one starts writing the post content (or the story), with paragraphs separated by a blank line, and so on.

  7. Run Chisel to produce posts in html with the following command:

    python ~/Sites/chisel/chisel.py
    
  8. Run a local server, and load web log in the browser2:

    cd ~/Sites/www
    python -m SimpleHTTPServer & open http://localhost:8000
    

  1. For a prettier Terminal, see zsh

  2. For clean URLs, and a better web server, see nginx