169 lines
6.1 KiB
Markdown
169 lines
6.1 KiB
Markdown
# coleslaw
|
|
|
|
[](https://travis-ci.org/kingcons/coleslaw)
|
|
[](http://quickdocs.org/coleslaw/)
|
|
|
|
<img src="https://raw.github.com/redline6561/coleslaw/master/themes/hyde/css/logo_medium.jpg" alt="coleslaw logo" align="right"/>
|
|
|
|
> [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
|
|
|
|
<!-- Don't let the first user select from multiple choises -->
|
|
|
|
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
|