# coleslaw [![Build Status](https://travis-ci.org/kingcons/coleslaw.svg?branch=master)](https://travis-ci.org/kingcons/coleslaw) [![Quicklisp](http://quickdocs.org/badge/coleslaw.svg)](http://quickdocs.org/coleslaw/) coleslaw logo > [Czeslaw Milosz](http://blog.redlinernotes.com/tag/milosz.html) was the writer-in-residence at UNC c. 1992. > I used to see him all the time at the Hardback Cafe, always sitting at a two-top > drinking coffee, reading, writing, eating chips and salsa. I remember a gentleness > behind the enormous bushy eyebrows and that we called him Coleslaw. - anon Coleslaw is Flexible Lisp Blogware similar to [Frog](https://github.com/greghendershott/frog), [Jekyll](http://jekyllrb.com/), or [Hakyll](http://jaspervdj.be/hakyll/). Have questions? - IRC in **#coleslaw** on Freenode! - Subscribe to the mailing list [**coleslaw@common-lisp.net**](https://mailman.common-lisp.net/listinfo/coleslaw). See the [wiki](https://github.com/redline6561/coleslaw/wiki/Example-sites) for a list of coleslaw-powered blogs. Coleslaw should run on any conforming Common Lisp implementations but testing is primarily done on [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.clozure.com/). ## Features * Git for storage * RSS/Atom feeds * A [Plugin API](http://github.com/redline6561/coleslaw/blob/master/docs/plugin-api.md) and [**plugins**](http://github.com/redline6561/coleslaw/blob/master/docs/plugin-use.md) for... | plugins | plugins | plugins | |--------------------------------------------------------|----------------------------------------------|-------------------------------------------------------| | Sitemap generation | Incremental builds | Analytics via Google or [Piwik](http://www.piwik.org) | | Comments via [Disqus](http://disqus.com/) | Comments via [isso](http://posativ.org/isso) | Hosting via [Amazon S3](http://aws.amazon.com/s3/) | | Hosting via [Github Pages](https://pages.github.com/) | Embedding [gfycats](http://gfycat.com/) | [Tweeting](http://twitter.com/) about new posts | | [Mathjax](http://mathjax.org/) | Posts in ReStructured Text | [Wordpress](http://wordpress.org/) import | | [Pygments](http://pygments.org/) | [colorize](http://www.cliki.net/colorize) | | ## Installation/Tutorial Step 1: Install this library. With [Roswell](https://roswell.github.io/), ``` sh $ ros install coleslaw $ export PATH="$HOME/.roswell/bin:$PATH" # If you haven't done this before ``` or ``` lisp (ql:quickload :coleslaw-cli) ``` Step 2: Initialize your blog repository. ``` sh $ mkdir yourblog ; cd yourblog $ git init $ coleslaw setup ``` ``` lisp (coleslaw-cli:setup) ``` Step 3: Write a post file in the current directory. The file should contain a certain metadata, so use the `coleslaw new` command, which instantiates a correct file for you. ``` sh $ coleslaw new Created a post 2017-11-06.post . ``` ``` lisp (coleslaw-cli:new "post") ``` Step 4: Generate the site from those post files. The result goes to the `deploy/` subdirectory. ``` sh $ coleslaw ``` ``` lisp (coleslaw-cli:generate) ``` Step 5: You can also launch a server... ``` sh $ coleslaw preview ``` ``` lisp (coleslaw-cli:preview) ``` Step 6: and watch the file system to automatically regenerate the site! ``` sh $ coleslaw watch # or even better, $ coleslaw watch-preview ``` ``` lisp (coleslaw-cli:watch) ;; watch-preview does not work on REPL right now ``` For further customization, edit the `.coleslawrc` file generated by `coleslaw setup`. Consult the [config docs](https://github.com/redline6561/coleslaw/blob/master/docs/config.md). ## The Content Format Coleslaw expects content to have a file extension matching the class of the content. (I.e. `.post` for blog posts, `.page` for static pages, etc.) There should also be a metadata header on all files starting and ending with the config-specified `:separator`, ";;;;;" by default. Example: ``` ;;;;; title: foo tags: bar, baz date: yyyy-mm-dd hh:mm:ss format: html (for raw html) or md (for markdown) excerpt: Can also be extracted from content (see :excerpt-sep config param) ;;;;; your post ``` Posts require the `title:` and `format:` fields. Pages require the `title:` and `url:` fields. To omit a field, simply do not have the line present, empty lines and fields (e.g. "tags:" followed by whitespace) will be ignored. ## Theming Two themes are provided: hyde, the default, and readable (based on [bootswatch readable](http://bootswatch.com/readable/)). A guide to creating themes for coleslaw lives [here](https://github.com/redline6561/coleslaw/blob/master/docs/themes.md). ## Deploying on a standalone server Coleslaw can deploy to a standalone server. If you want this server installation, initialize a bare git repo and set up the post-receive hook on that repo. * First initialize a [git bare repo](http://git-scm.com/book/en/Git-on-the-Server-Setting-Up-the-Server) on the server. * Copy [example post-receive hook][post_hook] to your blog's bare repo and set the executable bit (`chmod +x`). * Point the web server at `:deploy-dir` attribute on the config file. Or "deploy-dir/.curr" if the `versioned` plugin is enabled. [post_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive ## Hacking A core goal of *coleslaw* is to be both pleasant to read and easy to hack on and extend. If you want to understand the internals and bend *coleslaw* to do new and interesting things, I strongly encourage you to read the [Hacker's Guide to Coleslaw][hackers]. You'll find some current **TODO** items towards the bottom. [hackers]: https://github.com/redline6561/coleslaw/blob/master/docs/hacking.md