panda-2009.4.1: readme.md

## Panda: a simple blog engine in Haskell

### Features

#### simple file structure

    db
    |---- blog
    |     |---- 08-09-01 first post
    |     |---- 09-09-02 learn javascript.html
    |
    |---- tag
    |     |---- programming
    |     |---- funny
    |
    |---- static
          |---- About

#### simple config file

    blog_title    = C大调
    blog_subtitle = 野猫不吃薯片
    host_name     = jinjing.blog.easymic.com
    author_email  = nfjinjing@gmail.com

    navigation    = About
    per_page      = 7
    sidebar       = Blogroll.md
    favicon       = panda_icon.png

#### standard web technology

extend/customize with pure css and javascript ( note the custom part in css and js from the last section )

#### hacker friendly

* posts are in plain text
* SCM for publishing / data managing ( not really a feature, but a design goal from the beginning )
* blindly follows the KISS principle from code to UI: be a simple blog, no more no less

## Demo

### blog

[My blog](http://jinjing.easymic.com) source is available as a git repo:

    git clone git://github.com/nfjinjing/jinjing-blog.git

Or [browser](http://github.com/nfjinjing/jinjing-blog/tree/master) online

### config

[jinjing's blog config file](http://github.com/nfjinjing/jinjing-blog/blob/401a541443d88bbf8d844874c1473d4b3bc81784/config/site.txt)

## Install

### Quick setup

#### install [lighttpd](http://www.lighttpd.net/ )

Note: only version 1.4.19 has been successfully tested, 1.4.20 is bugged for reasons unknown.

#### install [ghc](http://www.haskell.org/ghc/download.html)

#### install [darcs](http://www.darcs.net/) for `cabal-install`

#### install [cabal-install](http://hackage.haskell.org/trac/hackage/wiki/CabalInstall)

    darcs get --partial http://darcs.haskell.org/cabal-install/
    cd cabal-install
    sh bootstrap.sh

#### install panda

    cabal update; cabal install panda

#### bootstrap

    # panda is a kibro project
    kibro new myblog
    cd myblog
    
    # get a template to start
    git clone git://github.com/nfjinjing/panda-template.git db
    sh db/extra/scripts/bootstrap.sh
    
#### run

    kibro start

It should be running on [http://127.0.0.1:3000](http://127.0.0.1:3000) now.

Since Panda is based on Kibro, it helps to read how [Kibro](http://chrisdone.com/blog/tag/Kibro) works.

### Goodies

Install `Ruby` / `Rake`, then `rake -T` to see a list of helper commands.

### Config

Edit `db/config/site.txt`

    blog_title   = My shiny blog
    host_name    = yourhost.com
    author_email = your_mail@yourhost.com

Restart required. (hint: `rake r`)

## User's guide

### posts

All posts are placed in `db/blog` folder, with naming convention [yy-mm-dd title], in Markdown format by default.

Markdown supports embedding HTML snippets, so embedding youtube video is a peace of cake.

<object width="425" height="344"><param name="movie" value="http://www.youtube.com/v/rEYg0Dqtogg&hl=en&fs=1"></param><param name="allowFullScreen" value="true"></param><embed src="http://www.youtube.com/v/rEYg0Dqtogg&hl=en&fs=1" type="application/x-shockwave-flash" allowfullscreen="true" width="425" height="344"></embed></object>
    
You can create static pages, in `db/static`, and link to them via `/static/static_file_name` inside your blogs.

For example `db/static/About`, where you can put some profile in.

### tagging

Create a file in `db/tag`, the name of the file will be the name of the new tag.
edit the tag file, insert the full name of a blog post, e.g. `08-09-04 Welcome to Panda`

### html / tex / restructured text format

Just create the file in blog as usual with an extension (e.g. html, rst, tex ), and you are all set.

### customize navigation bar

see example in `config/site`:

    navigation = About, Gallery

Multiple renderer supported, use extension as hints.

Note, the navigation configuration requires the full name of your static page, so you should include extension in configuration as well.

### customize sidebar

see example in `config/site`, `config/sidebar/Blogroll.md`

    sidebar    = Blogroll.md
  
Sidebar items are html snippets plugged into view. You can create these plugins in multiple formats, use extension.

### styling

Styling is done by editing `public/theme/blueprint/css/custom.css`, see the default `custom.css` for inspiration.

### theming

New theme can be created without touching `Panda` code, example blueprint theme in `db/config/theme/blueprint.txt`

    container  = container
    header     = column span-12 first
    navigation = column span-12 first large
    main       = column span-9 first
    sidebar    = column span-3 last
    footer     = footer

    css        = screen, blueprint-wp, custom
    js         = jquery-1.2.6.min, jquery.getUrlParam, jquery.highlight-2, custom


These are custom class names for each element block.

You can create new themes by adding theme definition files in `db/config/theme`, put theme resources under `db/public/theme/your_theme_name` and place

    theme = your_new_theme

inside `site.txt`.

note: `css` and `js` are required to be placed under `db/public/theme/your_theme_name/css` and `db/public/theme/your_theme_name/js`, leave out the file extensions in `site.txt`.

### syntax highlighting

    <object 
      type="text/html" \
      data="http://www.flickr.com/slideShow/index.gne \
      ?user_id=56167317@N00&tags=cat-hack" \
      width="500" height="500">
    </object>

Highlight for `HTML` is enabled by default, see `public/theme/blueprint/js/custom.js` for more language support.

Highlight style is configured at `config/theme/blueprint.txt`, just change `highlight/default` to any css inside `theme/blueprint/css/highlight`.


### analytics

Google analytics is available, put your `tracker_id` in `site.txt`, if you don't want analytics, ignore the setting.

Once site module is introduced, those `js` code could be configured to be gone forever, but not yet in the current release.

### final note

try to use `<h3>` for heading in your posts, at least `wordpress` is using this convention. `<h1>` is not styled in the blueprint theme, so they look kind of unfitted. But this does not stop anyone from styling `<h1>, <h2>` if wished.

### Links

* [Kibro](http://chrisdone.com/blog/tag/Kibro)
* [Panda on Jinjing's blog](http://jinjing.easymic.com/tag/Panda)
* [Source](http://github.com/nfjinjing/panda/tree)