May 13, 2012

Chisel

(This is 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/log/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, log/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 browser:

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

Optional: NGINX webserver

The following is a step-wise process of how I set-up my local web server environment using nginx on a Mac OS X.

  1. Download and install rudix, which is a collection of pre-built UNIX software delivered as packages for Mac OS X.
  2. Update /usr/local/etc/nginx/nginx.conf with server_name and location directives (see below). Ensure /etc/hosts file contains this following line:

    127.0.0.1 localhost ckunte.dev
    

    Run dscacheutil -flushcache, if necessary, so the /etc/hosts file is refreshed. Here are all the contents of my nginx.conf file:

    worker_processes 1;
    events {
        worker_connections 1024;
    }
    http {
        include mime.types;
        default_type application/octet-stream;
        sendfile on;
        keepalive_timeout 65;
        gzip on;
        server {
            listen 80;
            server_name ckunte.dev;
            root /Users/ckunte/Sites/ckunte.github.io;
            charset utf-8;
            location / {
                index index.html index.htm;
                try_files $uri.html $uri/ =404;
                error_page 404 = /404.html;
            }
        }
    }
    
  3. Test the thus updated nginx.conf with sudo nginx -t. With syntax ok, and the test successful, run sudo nginx (or if it’s already running, reload it with sudo nginx -s reload).

  4. Load http://ckunte.dev in a browser. (I quite like .dev, because it hints that it’s local and offline for development, testing, and proof-reading.)
  5. nginx is mapped to an alias in my ~/.zshrc as below:

    alias srv="sudo nginx"
    alias srvstop="sudo nginx -s stop"
    

    This allows me to run nginx only when I need it, and stop when I don’t.


  1. For a prettier Terminal, see zsh