Push closer to 0.9.6. Just tests and a merge left now...

NEWS.md

@@ -5,12 +5,15 @@
   To retain the previous behavior, add `(versioned)` to your config's
   `:plugins` list.
 * **SITE-BREAKING CHANGE**: Custom themes will be broken by a change
-  to URL handling. Previously, we were hand-constructed URLs in the
+  to URL handling. Previously, we were hand-constructing URLs in the
   templates. All site objects now store their URL in an instance slot.
   In general, hrefs should be of the form `href="{$config.domain}/{$obj.url}"> ...</a>`.
   Additionally, `{$month}` should become `{$month.name}`.
   Correspondingly, changes to `:routing` would previously break links in
   the templates but now work seamlessly.
+* **Docs**: Improved README. New Config File docs.
+* Loading content is more robust when empty lines or metadata are passed.
+  Thanks to @PuercoPop for the bug report and preliminary fix.
 * The config `:repo` option is now deprecated as its value has become
   a required argument to `coleslaw:main`. The value passed to `main`
   will override the config value going forward.

docs/config.md

@@ -15,8 +15,6 @@ The only *required* information in the config is:
 * `:title`        => to provide a site title
 * `:theme`        => to select one of the themes in "coleslaw/themes/"
 
-**TODO** Make sure this is actually true. Maybe without `:feeds` the publish method blows up? Test!
-
 It is usually recommend to start from the [example config][ex_config] and pare down from there.
 
 [ex_config]: https://github.com/redline6561/coleslaw/blob/master/examples/example.coleslawrc

docs/hacking.md

@@ -38,21 +38,6 @@ reduced runtime to 1.36 seconds, almost cutting it in half.
 
 ## Core Concepts
 
-### Data and Deployment
-
-**Coleslaw** is pretty fundamentally tied to the idea of git as both a
-backing data store and a deployment method (via `git push`). The
-consequence is that you need a bare repo somewhere with a post-recieve
-hook. That post-recieve hook ([example][post_receive_hook])
-will checkout the repo to a **$TMPDIR** and call `(coleslaw:main $TMPDIR)`.
-
-It is then coleslaw's job to load all of your content, your config and
-templates, and render the content to disk. Deployment is done by
-moving the files to a location specified in the config and updating a
-symlink.  It is assumed a web server is set up to serve from that
-symlink. However, there are plugins for deploying to Heroku, S3, and
-Github Pages.
-
 ### Plugins
 
 **Coleslaw** strongly encourages extending functionality via plugins.
@@ -79,8 +64,22 @@ and return rendered HTML.  **Coleslaw** defines a helper called
 there are RSS, ATOM, and sitemap templates *coleslaw* uses automatically.
 No need for individual themes to reimplement a standard, after all!
 
+Unfortunately, it is not very pleasant to debug broken templates.
+Efforts to remedy this are being pursued for the next release.
+Two particular issues to note are transposed Closure commands,
+e.g. "${foo}" instead of "{$foo}", and trying to use nonexistent
+keys or slots which fails silently instead of producing an error.
+
 ### The Lifecycle of a Page
 
+- `(progn
+     (load-config "/my/blog/repo/path")
+     (compile-theme (theme *config*)))`
+
+Coleslaw first needs the config loaded and theme compiled,
+as neither the blog location, the theme to use, and other
+crucial information are not yet known.
+
 - `(load-content)`
 
 A page starts, obviously, with a file. When *coleslaw* loads your
@@ -102,10 +101,10 @@ reverse-chronological index.
 
 - `(deploy dir)`
 
-Finally, we move the staging directory to a timestamped path under the
-the config's `:deploy-dir`, delete the directory pointed to by the old
-'.prev' symlink, point '.curr' at '.prev', and point '.curr' at our
-freshly built site.
+Finally, we move the staging directory to a path under the config's
+`:deploy-dir`. If the versioned plugin is enabled, it is a timestamped
+path and we delete the directory pointed to by the old '.prev' symlink,
+point '.curr' at '.prev', and point '.curr' at our freshly built site.
 
 ### Blogs vs Sites
 
@@ -116,13 +115,12 @@ INDEXes. Roughly speaking, a POST is a blog entry and an INDEX is a
 collection of POSTs or other content. An INDEX really only serves to
 group a set of content objects on a page, it isn't content itself.
 
-This isn't ideal if you're looking for a full-on static site
-generator.  Thankfully, Content Types were added in 0.8 as a step
-towards making *coleslaw* suitable for more use cases. Any subclass of
-CONTENT that implements the *document protocol* counts as a content
-type. However, only POSTs are currently included in the basic INDEXes
-since there isn't yet a formal relationship to determine which content
-types should be included on which indexes.  Users may easily implement
+Content Types were added in 0.8 as a step towards making *coleslaw*
+suitable for more use cases. Any subclass of CONTENT that implements
+the *document protocol* counts as a content type. However, only POSTs
+are currently included in the bundled INDEXes since there isn't yet a
+formal relationship to determine which content types should be
+included on which indexes. It is straightforward for users to implement
 their own dedicated INDEX for new Content Types.
 
 ### The Document Protocol
@@ -169,16 +167,14 @@ eql-specializing on the class, e.g.
 
 **Instance Methods**:
 
-- `page-url`: Generate a relative path for the object on the site,
-  usually sans file extension. If there is no extension, an :around
-  method adds "html" later. The `slug` slot on the instance is
-  conventionally used to hold a portion of the path that corresponds
-  to a unique Primary Key or Object ID.
+- `page-url`: Retrieve the relative path for the object on the site.
+  The implementation of `page-url` is not fully specified. For most
+  content types, we compute and store the path on the instance at
+  initialization time making `page-url` just a reader method.
 
 - `render`: A method that calls the appropriate template with `theme-fn`,
   passing it any needed arguments and returning rendered HTML.
 
-
 **Invariants**:
 
 - Any Content Types (subclasses of CONTENT) are expected to be stored in
@@ -224,8 +220,6 @@ PAGE, a content type for static page support, is available as a plugin.
 * Finish docs updates to:
   * themes.md     -> Note debugging issues. Valid slots. Changed URL handling.
   * plugin-use.md -> Incremental plugin, Versioned plugin. Twitter summary cards.
-  * hacking.md    -> Any changes to Document Protocol?
-  * config.md     -> Test various empty config slots.
 * A real test suite with Stefil that at *least* tests:
   * `read-content`
   * `load-config`
@@ -262,29 +256,24 @@ that are useful to the user. Example errors users have encountered:
    should tell the user what file failed and why. We also should
    probably enforce more constraints about metadata. E.g. Empty
    metadata is not allowed/meaningful. Trailing space after separator, etc.
-2. Custom themes that try to access non-existent properties of content
-   do not currently error. They just wind up returning whitespace.
-   When the theme compiles, we should alert the user to any obvious
-   issues with it.
-3. Trying to load content from the bare repo instead of the clone.
+2. Trying to load content from the bare repo instead of the clone.
    i.e. Specifying the `:repo` in .coleslawrc as the bare repo.
    The README should clarify this point and the need for posts to be
    ".post" files.
+3. Custom themes that try to access non-existent properties of content
+   do not currently error. They just wind up returning whitespace.
+   When the theme compiles, we should alert the user to any obvious
+   issues with it.
 4. Dear Lord it was miserable even debugging a transposed character error
    in one of the templates. "${foo}" instead of "{$foo}". But fuck supporting
    multiple templating backends I have enough problems. What can we do?
 
 ### Scripting Conveniences
 
-1. The getting started process has been simplified for new users.
-   They are able to just place a config in $HOME or their repo and do
-   `(progn
-      (ql:quickload :coleslaw)
-      (coleslaw:main "/path/to/my/blog-repo"))`.
-2. We may also add command-line tools/scripts to run coleslaw, set up
-   the db for incremental builds, scaffold a new post, etc. for new users.
-   Xach's buildapp or cl-launch would be useful here. frog and hakyll are
-   good points of inspiration as well.
+It would be convenient to add command-line tools/scripts to run coleslaw,
+set up the db for incremental builds, scaffold a new post, etc. for new users.
+Xach's buildapp or Fare's cl-launch would be useful here. frog and hakyll are
+reasonable points of inspiration for commands to offer.
 
 ### Plugin Constraints
 
@@ -335,7 +324,6 @@ Unfortunately, this does not solve:
    Content Types it includes or the CONTENT which indexes it appears
    on is not yet clear.
 
-[post_receive_hook]: https://github.com/redline6561/coleslaw/blob/master/examples/example.post-receive
 [closure_template]: https://github.com/archimag/cl-closure-template
 [api_docs]: https://github.com/redline6561/coleslaw/blob/master/docs/plugin-api.md
 [clmd]: https://github.com/gwkkwg/cl-markdown

src/config.lisp

@@ -18,6 +18,10 @@
    (theme           :initarg :theme          :reader theme)
    (title           :initarg :title          :reader title))
   (:default-initargs
+   :feeds        nil
+   :license      nil
+   :plugins      nil
+   :sitenav      nil
    :charset      "UTF-8"
    :lang         "en"
    :page-ext     "html"