commit 89db40a55275b2086e873d322013c98c14b68cfe Masataro Asai <guicho2.71828@gmail.com> 2019-10-26 12:10:31 -0400 [README] tutorial for CLI / REPL commands
README.md | 126 +++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 88 insertions(+), 38 deletions(-)
diff --git a/README.md b/README.md index 01a5045..e330f58 100644 --- a/README.md +++ b/README.md @@ -36,48 +36,84 @@ testing is primarily done on [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.c | [Pygments](http://pygments.org/) | [colorize](http://www.cliki.net/colorize) | | -## Installation - - -Coleslaw can either be run **manually** on a local machine or -triggered **automatically** on git push to a server. If you want a -server install, run these commands on your server _after_ setting up a -[git bare repo](http://git-scm.com/book/en/Git-on-the-Server-Setting-Up-the-Server). -Otherwise, run the commands on your local machine. - -1. Install a Common Lisp implementation (we recommend SBCL) and - [Quicklisp](http://quicklisp.org/). -2. Place a config file for coleslaw in your `$HOME` directory. If you - want to run multiple blogs with coleslaw, you can keep each blog's - config file in that blog's repo. Feel free to copy and edit the - [example config][ex_config] or consult the [config docs][conf_docs] - to create one from scratch. -3. This step depends on whether you're setting up a local or server install. - * Server Install: Copy and `chmod +x` the - [example post-receive hook][post_hook] to your blog's bare repo. - * Local Install: Just run the following commands in the - REPL whenever you're ready to regenerate your blog: - ``` - (ql:quickload :coleslaw) - (coleslaw:main "/path/to/my/blog/") - ``` -4. Optionally, point the web server of your liking at your config-specified - `:deploy-dir`. Or "deploy-dir/.curr" if the `versioned` plugin is enabled. -5. If you use Emacs, consider installing - [coleslaw-mode](https://github.com/equwal/coleslaw-mode) to author your - posts. - -Now just write posts, git commit and build by hand or by push. - -[ex_config]: https://github.com/redline6561/coleslaw/blob/master/examples/example.coleslawrc -[conf_docs]: https://github.com/redline6561/coleslaw/blob/master/docs/config.md -[post_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive +## 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.) +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 @@ -108,6 +144,20 @@ Two themes are provided: hyde, the default, and readable (based on 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