diff --git a/DESI.md b/DESI.md new file mode 100644 index 0000000..8e8f0af --- /dev/null +++ b/DESI.md @@ -0,0 +1,74 @@ +Data +==== + +Every template gets an object with the exact same structure - whether it's a template or a widget or a page or a post. + +Here we only document Desirae's default behavior, but there are many objects added for compatibility with Ruhoh that are not documented. + +``` +desi = {} +``` + +desi +==== + +* `config` - literally `config.yml`, parsed +* `site` - literally `site.yml`, parsed +* `authors` - literally the authors from `authors/*.yml`, parsed +* `author` - the primary author of the site +* `env` - urls and paths for this build (be it production, development, staging, etc) +* `content` - pre-rendered content (i.e. content rendered into the post layout rendered into the default layout) +* `collection` - config related to this collection +* `entity` - the page, post, article, etc that is the focus of the present template process +* `themes` - all themes +* `theme` - the default theme +* `layout` - the selected layout for this theme +* `satch` - the selected swatch for this theme +* `categories` - all categories +* `tags` - all tags +* `styles` - ??? goes into the final template in the head +* `scripts` - ?? that goes into the final template just before the body close + +desi.entity +=========== + +stuff + +* `uuid` +* `title` +* `disqus_url` +* `disqus_identifier` + +more stuff + +* `type` - `post`, `page`, etc +* `authors` - literally the relevant authors from `authors/*.yml`, parsed +* `author` - the primary author of this entity +* `theme` - null or a non-default theme +* `layout` - null or a non-default layout for this theme +* `swatch` - null or a non-default swatch for this theme +* `categories`: [] // *all* categories in all collections +* `tags`: [] // *all* categories in all collections +* `production_canonical_url` the PRODUCTION canonical_url for this entity +* `production_url` the PRODUCTION url for this entity +* `production_path` the PRODUCTION path for this entity +* `url` the full url in the current environment (might be production, development, etc) +* `path` the non-host part (i.e. `/compiled_dev/articles/my-first-post.html`) +* `previous` the previous entity in this collection +* `next` the next entitiy in this collection + +NOTE: Plugins, widgets, etc SHOULD NOT modify config, site, authors, author, or env. + +desi.posts +========== + + , posts: { collated: desi.collated } + +desi.config +=========== + +desi.site +=========== + +desi.env +=========== diff --git a/README.md b/README.md index 286a50d..b7eaa38 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ Desirae ===== +(in development) + A blog platform built for Developers, but with normal people in mind. Desirae runs entirely in the browser, but needs a little help from Node.js for saving and retrieving files. @@ -20,39 +22,6 @@ Node (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). -Install and Usage -================= - -If you're on OS X or Linux, it's as easy as pie to install and use Desirae. - -```bash -git clone git@github.com:DearDesi/desirae.git -pushd desirae - -# Downloads and installs node.js and a few other tools Desirae needs -bash setup.sh ./blog -``` - -After the initial installation you can launch Dear Desi, the Web-based configuration and build tool like so: - -``` -deardesi ./blog 65080 -``` - -Or, if you prefer, you can build with `desirae` from the command line: - -``` -desirae build ./blog - -desirae build-dev ./blog -``` - -Create a new Post ------------------ - -``` -desirae post "My First Post" -``` Configuration ============= @@ -65,58 +34,6 @@ There are a few configuration files: If any of these files change, the entire site needs to be retemplated. -Widgets -======= - -All widgets should export an object with a `create(widgetConf, desiState)` function that returns a promise. - -```yaml -widgets: - foogizmo: - # only stuff that is intensely specific to foogizmo goes here - # stuff like google ad and disqus ids should go in config.yml or data.yml - config: - foobeep: boop - - handle: - - html - - markdown - handlers: - post: fooposter - page: foopager -``` - -```javascript -'use strict'; - -module.exports.Foogizmo.create = function (foogizmoConf, desiState) { - return new Promise(function (resolve) { - - function pager(desiPageState) { - // Do processing - - return Promise.resolve(); - } - - function poster(desiPostState) { - // Do processing - - desiPostState.fooembedinator = function (fooval) { - // figure out what type of link fooval is and return iframe html - return '' - } - } - - resolve({ foopager: pager, fooposter: poster }); - }); -} -``` - -Overlays --------- - -For any config a widget uses, it should also check on post.fooconfig and theme.fooconfig to make sure that they don't override the foogizmo.config.fooconfig - Server ====== @@ -137,17 +54,20 @@ GET /api/fs/walk ```json [ { "name": "happy-new-year.md" + , "createdDate": "2015-01-05T18:19:30.000Z" , "lastModifiedDate": "2015-01-05T18:19:30.000Z" , "size": 2121 , "relativePath": "posts/2015" } , { "name": "tips-for-the-ages.jade" + , "createdDate": "2014-06-16T18:19:30.000Z" , "lastModifiedDate": "2014-06-16T18:19:30.000Z" , "size": 389 , "relativePath": "posts" } , { "name": "my-first-post.html" + , "createdDate": "2013-08-01T22:47:37.000Z" , "lastModifiedDate": "2013-08-01T22:47:37.000Z" , "size": 4118 , "relativePath": "posts/2013" @@ -183,6 +103,7 @@ GET /api/fs/files ```json { "path": "posts/intro-to-http-with-netcat-node-connect.md" +, "createdDate": "2013-08-01T22:47:37.000Z" , "lastModifiedDate": "2013-08-01T22:47:37.000Z" , "contents": "..." , "sha1": "6eae3a5b062c6d0d79f070c26e6d62486b40cb46" @@ -236,6 +157,7 @@ POST http://local.dear.desi:8080/api/fs/files?compiled=true&_method=PUT { "path": "posts/foo.md" , "name": "foo.md" , "relativePath": "posts" + , "createdDate": "2013-08-01T22:47:37.000Z" , "lastModifiedDate": "2013-08-01T22:47:37.000Z" , "contents": "..." , "sha1": "6eae3a5b062c6d0d79f070c26e6d62486b40cb46" @@ -259,10 +181,18 @@ The response may include errors of all shapes and sizes. } ``` -**TODO** Allow rename and delete? +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. diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..2d262ac --- /dev/null +++ b/TODO.md @@ -0,0 +1,85 @@ +format should change permalink +date +show file path +show prod url +show dev url + + +POST tests +create a title and delete it (no error) +change the format. does the permalink change? (yes) +change the permalink. change the title. does the permalink stay? (yes) + +change the format. does the permalink change? (yes) +change the format in the frontmatter permalink. does the format change? (yes) + +create a description and delete it (no error) +create a description. does the frontmatter change? (yes) + + +protection +Don't allow changing the uuid, original_url, or original_date + +TODO +--- + +check that no other post uses the same permalink + + + +default data-model 'ruhoh@2.2' +other data-model 'desirae@1.0' + +Widgets +======= + +All widgets should export an object with a `create(widgetConf, desiState)` function that returns a promise. + +```yaml +widgets: + foogizmo: + # only stuff that is intensely specific to foogizmo goes here + # stuff like google ad and disqus ids should go in config.yml or data.yml + config: + foobeep: boop + + handle: + - html + - markdown + handlers: + post: fooposter + page: foopager +``` + +```javascript +'use strict'; + +module.exports.Foogizmo.create = function (foogizmoConf, desiState) { + return new Promise(function (resolve) { + + function pager(desiPageState) { + // Do processing + + return Promise.resolve(); + } + + function poster(desiPostState) { + // Do processing + + desiPostState.fooembedinator = function (fooval) { + // figure out what type of link fooval is and return iframe html + return '' + } + } + + resolve({ foopager: pager, fooposter: poster }); + }); +} +``` + +Overlays +-------- + +For any config a widget uses, it should also check on post.fooconfig and theme.fooconfig to make sure that they don't override the foogizmo.config.fooconfig + + diff --git a/bower.json b/bower.json index d65095a..14ac305 100644 --- a/bower.json +++ b/bower.json @@ -5,22 +5,27 @@ "AJ ONeal " ], "description": "A blogging platform in the browser. Wow!", - "main": "deardesi.js", + "main": "desirae.js", "moduleType": [ "globals", "node" ], "keywords": [ + "desirae", "dear", "desi", "deardesi", "blog", "blogging", "platform", + "ruhoh", + "nanoc", + "jekyll", + "octopress", "browser" ], "license": "Apache2", - "homepage": "http://github.com/coolaj86/deardesi", + "homepage": "http://github.com/DearDesi/desirae", "ignore": [ "**/.*", "node_modules", @@ -29,22 +34,13 @@ "tests" ], "dependencies": { - "mustache": "~0.8.2", "bluebird": "~2.6.2", - "rsvp": "~3.0.16", "escape-string-regexp": "~1.0.2", - "js-yaml": "~3.2.5", - "path": "~3.46.1", "forEachAsync": "~5.0.5", - "node-uuid": "~1.4.2", + "js-yaml": "~3.2.5", "markdown-it": "~3.0.2", - "angular": "~1.3.8", - "angular-route": "~1.3.8", - "html5-boilerplate": "~4.3.0", - "bootstrap": "~3.3.1", - "md5": "~0.1.3" - }, - "resolutions": { - "bluebird": "~2.6.2" + "mustache": "~0.8.2", + "node-uuid": "~1.4.2", + "path": "~3.46.1" } } diff --git a/deardesi.js b/desirae.js similarity index 100% rename from deardesi.js rename to desirae.js diff --git a/swatches.yml b/example/swatches.yml similarity index 100% rename from swatches.yml rename to example/swatches.yml diff --git a/index.html b/index.html deleted file mode 100644 index bf956ca..0000000 --- a/index.html +++ /dev/null @@ -1,121 +0,0 @@ - - - - - - - - - - Dear Desi - Static Blog Generator - - - - - - - - - - - - - - - - -
-
-
-
Desirae - -
- -
-
- - -
-
- -
- - - - - Fork me on GitHub - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -