preparing for 0.9 release

README.md

@@ -1,27 +1,123 @@
-Desirae
+Did you mean DearDesi?
-=====
+======================
 
-(in development)
+If you're looking for [DearDesi](http://dear.desi), the DIY blog platform for normal people
+you should go to <http://dear.desi>.
 
-A blog platform built for Developers, but with normal people in mind.
+Desirae (this repo) is the code that programmers to use to make DearDesi better
+for everyone and to make Desirae-compatible blog platforms. (it's blog-ception!)
 
-Desirae runs entirely in the browser, but needs a little help from Node.js for saving and retrieving files.
+Desirae (v0.9)
+=======
 
-She can also be run from entirely headless from node.js.
+Desirae is a static webpage compiler written in JavaScript.
 
-Key Features
+It can run entirely in the browser
-------------
+(with a little help from a minimal just to serve to read and save files).
 
-Really good use of `try { ... } catch(e) ...` - it won't all blow up at the slightest parse error (*cough* ruhoh *cough* jekyll)... bless me.
+It can also run entirely from the commandline (with io.js / node.js).
 
-JavaScript - it's so stable it takes 10 years to get new any features. Won't break every time you upgrade OS X and reinstall brew (*cough* ruby).
+**Features:**
 
-Browser (optional) - using your front-end templates to build in your front-end? Imagine that!
+  * `JavaScript` - it's so stable it takes 10 years to get new any features.
+    * Won't break every time you upgrade OS X and reinstall `brew` (*cough* ruby)
+  * Decent use of `try { ... } catch(e) ...` and `promise.catch()`
+    * the idea is that it shouldn't blow up at the slightest parse error without telling you which page is to blame (*cough* ruhoh *cough* jekyll)... bless me
+  * Browser (optional)
+    * using your front-end templates to build in your front-end? Imagine that!
+  * io.js (node.js) (optional)
+    * if you'd prefer to go headless, you can.
+  * The server is *very* minimal and could easily be implemented in any language (such as ruby or python).
 
-Node (optional) - if you'd prefer to go headless, you can.
+Installation
+============
 
-The server is *very* minimal and could easily be implemented in any language (such as ruby or python).
+```bash
+bower install --save desirae
 
+npm install --save desirae
+```
+
+Why
+===
+
+Because I hate ruby.
+
+Well, I don't hate it, but it hates me. Or at least it moves too fast and has
+too many breaking changes between updates.
+
+Anyway, I had to drop [ruhoh](http://ruhoh.com) because I made a new year's resolution to blog
+more (last year I made dozens of gists and 0 blog posts) and I just couldn't get the right ruby
+versions and gems and whatnot... so I gave up and wrote my own (because I needed something
+compatible with ruhoh).
+
+Usage Overview
+==============
+
+### Before we get started
+
+(disclaimers)
+
+**Browser**: The default fs adapter will request the config files from `/api/fs/`. 
+
+**Node**: Remember that desirae is built browser-first, and optimized to reduce the number of round-trips
+(in case someone actually desides to host a Desi service, y'know?), so... the node adapter is built with
+the server in mind. If you can't respect that, don't look at the code. :-)
+
+**NOTE**: The mixing of `snake_case` with `camelCase` is somewhat intentional.
+It's an artifact of this project being born out of the ashes of my
+[ruhoh](http://ruhoh.com/) blog, which is built in ruby and uses YAML.
+
+### Getting Started
+
+First off you need to declare a state object that will be used in every *desirae* action.
+
+```javascript
+var desi = {}
+  ;
+```
+
+After that you'll initialize Desirae with an *environment*.
+
+```javascript
+Desirae.init(
+  desi
+, { url:                'https://johndoe.exmaple.com/blog'
+  , base_url:           'https://johndoe.exmaple.com'
+  , base_path:          '/blog'
+  , compiled_path:      'compiled_dev'
+
+                        // default: continue when possible
+  , onError:            function (e) {
+                          return Promise.reject(e);
+                        }
+
+                        // io.js / node.js only
+  , working_path:       './path/to/blog'
+  }
+).then(function () {
+  console.log('Desirae is initialized');
+});
+```
+
+Using the paths specified in the environment it will read the appropriate
+`config.yml`, `site.yml`, and `authors/*.yml` files to initialize itself.
+
+Then you can specify to build the static blog. You'll need to pass the environment again.
+
+```
+Desirae.buildAll(desi, env).then(function () {
+  console.log('Desirae built your blog!');
+});
+```
+
+Finally, you save the built out to disk.
+
+```
+Desirae.write(desi, env).then(function () {
+  console.log('Desirae pushd all files to the appropriate fs adapter!');
+});
+```
 
 Configuration
 =============
@@ -30,10 +126,82 @@ There are a few configuration files:
 
 * `site.yml` is stuff that might be unique to your site, such as (title, url, adwords id, etc)
 * `authors/<<your-handle.yml>>` contains information about you (name, handle, facebook, etc)
-* `desirae.yml` contains directives that describe *how* the blog should be compiled - more technical stuff.
+* `config.yml` contains directives that describe *how* the blog should be compiled - more technical stuff.
 
 If any of these files change, the entire site needs to be retemplated.
 
+API
+===
+
+I'd like to make the plugin system connect-style API for adding plugins or whatever so that,
+for example, so you could have a custom markdown preprocessor (that handles includes, perhaps)
+and still pass the string along to the 'real' markdown parser afterwards.
+
+But here's what I've got so far:
+
+## Rendering Engines
+
+### (html, markdown, jade)
+
+* `Desirae.registerRenderer(ext, fn)`
+
+For example, if you want to add the ability to render from `slim` or `haml`
+instead of just `markdown` you could find the appropriate
+JavaScript module (or make requests to an API service that renders them for you) and do this
+
+```javascript
+var slim = exports.slimjs || require('slimjs')
+  ;
+
+function render(contentstr/*, desi*/) {
+  return PromiseA.resolve(slim(contentstr));
+}
+
+Desirae.registerRenderer('.slim', render);
+```
+
+## Data Mapping
+
+### (desirae, ruhoh, etc)
+
+* `Desirae.registerDataMapper(ext, fn)`
+
+If you want to use a non-desirae theme that uses attributes in a different than
+how Desirae creates the view object internally
+(i.e. it wants `{{ page.name }}` instead of `{{ entity.title }}`), you can use a
+data mapper to accomplish this.
+
+Please try not to modify the original object if you can avoid it.
+
+*TODO: maybe pass in a two-level deep shallow copy ?*
+
+```javascript
+Desirae.registerDataMapper('ruhoh@3.0', function (view) {
+  return {
+    page: {
+      name: view.entity.title
+    }
+  , author: {
+      nickname: view.author.twitter
+    }
+    // ... 
+  };
+});
+```
+
+The default datamapper is `ruhoh@2.6`
+
+(note that that might be misnamed, I'm a little confused as to how Ruhoh's template versions correspond
+to Ruhoh proper versions).
+
+## Adapters
+
+### (fs, http, dropbox)
+
+I'd love to work with anyone who is familiar with the Dropbox or similar APIs.
+
+I think it would be awesome to support various means of storage. Perhaps github gists too.
+
 
 Server
 ======
@@ -187,12 +355,3 @@ POST /api/fs/copy
 ```json
 { files: { "assets/logo.png": "compiled/assets/logo.png" } }
 ```
-
-
-TODO
-----
-
-**TODO** Allow rename and delete?
-
-option for client write to a hidden `.desi-revisions` (as well as indexeddb)
-to safeguard against accidental blow-ups for people who aren't using git.

package.json

@@ -1,14 +1,14 @@
 {
   "name": "desirae",
-  "version": "0.1.0",
+  "version": "0.9.0",
-  "description": "An in-browser knockoff of the Ruhoh static blog generator. (similar to Jekyll, Octopress, Nanoc, etc)",
+  "description": "An in-browser static blog library and static site generator. Similar to Jekyll, Octopress, Nanoc, etc",
   "main": "desirae.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com:coolaj86/deardesi.git"
+    "url": "git@github.com:DearDesi/desirae.git"
   },
   "keywords": [
     "dear",
@@ -25,9 +25,9 @@
   "author": "AJ ONeal",
   "license": "Apache2",
   "bugs": {
-    "url": "https://github.com/coolaj86/deardesi/issues"
+    "url": "https://github.com/DearDesi/desirae/issues"
   },
-  "homepage": "https://github.com/coolaj86/deardesi",
+  "homepage": "https://github.com/DearDesi/desirae",
   "dependencies": {
     "bluebird": "^2.5.3",
     "escape-string-regexp": "^1.0.2",