preparing for 0.9 release
This commit is contained in:
AJ ONeal
parent
98f998088a
commit
842cabed78
205
README.md
205
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.
|
||||
|
|
|
|||
10
package.json
10
package.json
|
|
@ -1,14 +1,14 @@
|
|||
{
|
||||
"name": "desirae",
|
||||
"version": "0.1.0",
|
||||
"description": "An in-browser knockoff of the Ruhoh static blog generator. (similar to Jekyll, Octopress, Nanoc, etc)",
|
||||
"version": "0.9.0",
|
||||
"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",
|
||||
|
|
|
|||
Loading…
Reference in New Issue