README.md (5561 bytes)
1 # coleslaw 2 3 [](https://travis-ci.org/kingcons/coleslaw) 4 [](http://quickdocs.org/coleslaw/) 5 6 <img src="https://raw.github.com/redline6561/coleslaw/master/themes/hyde/css/logo_medium.jpg" alt="coleslaw logo" align="right"/> 7 8 > [Czeslaw Milosz](http://blog.redlinernotes.com/tag/milosz.html) was the writer-in-residence at UNC c. 1992. 9 > I used to see him all the time at the Hardback Cafe, always sitting at a two-top 10 > drinking coffee, reading, writing, eating chips and salsa. I remember a gentleness 11 > behind the enormous bushy eyebrows and that we called him Coleslaw. - anon 12 13 Coleslaw is Flexible Lisp Blogware similar to [Frog](https://github.com/greghendershott/frog), [Jekyll](http://jekyllrb.com/), or [Hakyll](http://jaspervdj.be/hakyll/). 14 15 Have questions? 16 - IRC in **#coleslaw** on Freenode! 17 - Subscribe to the mailing list [**coleslaw@common-lisp.net**](https://mailman.common-lisp.net/listinfo/coleslaw). 18 19 See the [wiki](https://github.com/redline6561/coleslaw/wiki/Example-sites) for a list of coleslaw-powered blogs. 20 21 Coleslaw should run on any conforming Common Lisp implementations but 22 testing is primarily done on [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.clozure.com/). 23 24 ## Features 25 26 * Git for storage 27 * RSS/Atom feeds 28 * Themes 29 * A [Plugin API](docs/plugin-api.md) and [**plugins**](docs/plugin-use.md) for... 30 31 | plugins | plugins | plugins | 32 |--------------------------------------------------------|----------------------------------------------|-------------------------------------------------------| 33 | Sitemap generation | Incremental builds | Analytics via Google or [Piwik](http://www.piwik.org) | 34 | Comments via [Disqus](http://disqus.com/) | Comments via [isso](http://posativ.org/isso) | Hosting via [Amazon S3](http://aws.amazon.com/s3/) | 35 | Hosting via [Github Pages](https://pages.github.com/) | Embedding [gfycats](http://gfycat.com/) | [Tweeting](http://twitter.com/) about new posts | 36 | [Mathjax](http://mathjax.org/) | Posts in ReStructured Text | [Wordpress](http://wordpress.org/) import | 37 | [Pygments](http://pygments.org/) | [colorize](http://www.cliki.net/colorize) | | 38 39 40 ## Installation/Tutorial 41 42 <!-- Don't let the first user select from multiple choises --> 43 44 Step 1: Install this library. 45 46 ``` 47 $ ros install coleslaw-org/coleslaw # With [Roswell](https://roswell.github.io/) 48 $ export PATH="$HOME/.roswell/bin:$PATH" # If you haven't done this before for Roswell 49 or 50 CL-USER> (ql:quickload :coleslaw-cli) 51 ``` 52 53 Step 2: Initialize your blog repository. 54 55 ``` 56 $ mkdir yourblog ; cd yourblog 57 $ git init 58 $ coleslaw setup # or 59 CL-USER> (coleslaw-cli:setup) 60 ``` 61 62 `coleslaw setup` / `(coleslaw-cli:setup)` will generate a `.coleslawrc` file in 63 the current directory, which contains the configuration of the static website. 64 65 Step 3: Write a post file in the current directory. 66 The file should contain a certain metadata, so use the `coleslaw new` command, 67 which instantiates a correct file for you. 68 69 ``` 70 $ coleslaw new 71 Created a post 2017-11-06.post . 72 # or 73 CL-USER> (coleslaw-cli:new "post") 74 Created a post 2017-11-06.post . 75 ``` 76 77 Step 4: Generate the site from those post files. 78 The result goes to the *staging directory* specified in the `.coleslawrc` file. 79 The staging directory is `/tmp/coleslaw/` by default. 80 81 ``` 82 $ coleslaw # or 83 $ coleslaw generate # or 84 $ coleslaw stage # or 85 CL-USER> (coleslaw-cli:generate) ; or 86 CL-USER> (coleslaw-cli:stage) ; --- these are all aliases 87 ``` 88 89 Step 5: You can launch a web server to check the result on a browser. 90 (Running a webserver sometimes has a benefit over just opening an html file, 91 e.g. the relative links behaves differently on a file:/// protocol) 92 93 ``` 94 $ coleslaw preview # or 95 CL-USER> (coleslaw-cli:preview) 96 ``` 97 98 Step 6: and watch the file system to automatically regenerate the site! 99 100 ``` 101 $ coleslaw watch # or even better, 102 $ coleslaw watch-preview # or, on REPL, 103 CL-USER> (coleslaw-cli:watch) ;; watch-preview does not work on REPL right now 104 ``` 105 106 Step 7: When you think your article is publishable, run 107 108 ``` 109 $ coleslaw deploy # or 110 CL-USER> (coleslaw-cli:deploy) 111 ``` 112 113 To move the contents in the staging dir to the deploy dir. 114 By default, this deploy command uses `rsync` to sync the directories, 115 where the deploy dir could be a remote directory on the server which is running your website. 116 By using a plugin, you can customize this behavior e.g. running the deploy on gh-pages. 117 118 For further customization, e.g. adding a new plugin, developing a new plugin, changing the deploy option, or creating a new theme, 119 see the [config docs](docs). 120 121 We provide three default themes: hyde, the default, and readable (based on 122 [bootswatch readable](http://bootswatch.com/readable/)). 123 124 A core goal of *coleslaw* is to be both pleasant to read and easy to 125 hack on and extend. If you want to understand the internals and bend 126 *coleslaw* to do new and interesting things, I strongly encourage you 127 to read the [Hacker's Guide to Coleslaw][hackers]. You'll find some 128 current **TODO** items towards the bottom. 129 130 [hackers]: docs/hacking.md