preparing for 0.9 release
This commit is contained in:
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
|
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)
|
* `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)
|
* `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.
|
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
|
Server
|
||||||
======
|
======
|
||||||
|
@ -187,12 +355,3 @@ POST /api/fs/copy
|
||||||
```json
|
```json
|
||||||
{ files: { "assets/logo.png": "compiled/assets/logo.png" } }
|
{ 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",
|
"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",
|
"main": "desirae.js",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"test": "echo \"Error: no test specified\" && exit 1"
|
"test": "echo \"Error: no test specified\" && exit 1"
|
||||||
},
|
},
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "git@github.com:coolaj86/deardesi.git"
|
"url": "git@github.com:DearDesi/desirae.git"
|
||||||
},
|
},
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"dear",
|
"dear",
|
||||||
|
@ -25,9 +25,9 @@
|
||||||
"author": "AJ ONeal",
|
"author": "AJ ONeal",
|
||||||
"license": "Apache2",
|
"license": "Apache2",
|
||||||
"bugs": {
|
"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": {
|
"dependencies": {
|
||||||
"bluebird": "^2.5.3",
|
"bluebird": "^2.5.3",
|
||||||
"escape-string-regexp": "^1.0.2",
|
"escape-string-regexp": "^1.0.2",
|
||||||
|
|
Loading…
Reference in New Issue