diff --git a/NEWS.md b/NEWS.md index d1e6886..5b119b3 100644 --- a/NEWS.md +++ b/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}"> ...`. 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. diff --git a/docs/config.md b/docs/config.md index d2925c2..5814c57 100644 --- a/docs/config.md +++ b/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 diff --git a/docs/hacking.md b/docs/hacking.md index 4c5b91e..9d5c47c 100644 --- a/docs/hacking.md +++ b/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 diff --git a/src/config.lisp b/src/config.lisp index 14e3dae..d73a98a 100644 --- a/src/config.lisp +++ b/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"