docs

assemble · Feb 15, 2015 · 66bd0a8 · 66bd0a8
1 parent e26e991
commit 66bd0a8
Show file tree

Hide file tree

Showing 12 changed files with 802 additions and 131 deletions.
diff --git a/docs/_verb/assemble.files.md b/docs/_verb/assemble.files.md
@@ -10,8 +10,8 @@ Returns something like:
 
 ```js
 { home: {
-    base: '/site/template/pages/',
-    content: '{{ msg }}',
+    base: '/site/template/',
+    content: 'foo {{ msg }} bar',
     cwd: '/site',
     data: { msg: 'hello world', src: [Object], dest: [Object] },
     options: {},
@@ -21,6 +21,8 @@ Returns something like:
 }}
 ```
 
+**Usage in plugins**
+
 When `files` is used inside a plugin, the stream must be bound to the session via `session.bindEmitter`:
 
 ```js

diff --git a/docs/_verb/helpers.md b/docs/_verb/helpers.md
@@ -2,6 +2,14 @@
 
 > Using helpers in templates
 
+
+## Overview
+
+- Helpers are stored on the `assemble.options` object.
+- Helpers can be defined and used in any way you need in your projects. 
+- Assemble uses the same API to set [default options][built-in options] for some of assemble's built-in features, such as `layout` and `layoutdir`. Defaults can easily be changed, disabled or overridden.
+
+
 ## What are helpers?
 
 Helpers are just regular javascript functions that can be used in templates. Helpers are used to inject or transform data or content. 

diff --git a/docs/_verb/built-in-options.md → docs/_verb/options-built-in.md b/docs/_verb/built-in-options.md → docs/_verb/options-built-in.md
diff --git a/docs/_verb/options.assets.md b/docs/_verb/options.assets.md
@@ -1,45 +1,23 @@
-The `assets` property on the options is used to calculate the relative path from any generated files (usually HTML) to whatever folder is specified in the `assets` option.  For example, say you have the following template, `foo.hbs`:
+# options.assets
 
-```handlebars
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <title>Foo</title>
-    <link rel="stylesheet" href="\{{assets}}/css/styles.css">
-  </head>
-  <body>
-    \{{> body }}
-  </body>
-</html>
-```
+The `assets` property on the options is used to calculate the relative path from any generated files (usually HTML) to whatever folder is specified in the `assets` option. 
 
-Note the `\{{assets}}` handlebars expression. When `foo.hbs` is rendered, this expression will be resolved with the value that is calculated from `foo`'s destination to whatever value is defined in  `options.assets`. So this:
+**Example**
+
+Define the `assets` option in your project's [assemblefile.js](./assemblefile.md):
 
 ```js
-assemble: {
-  options: {
-    assets: 'dist/public'
-  },
-  site: {
-    src: 'templates/foo.hbs',
-    dest: 'dist/'
-  }
-}
+assemble.option('assets', 'site/public');
+```
+
+Now you can use it in templates:
+
+```handlebars
+<link rel="stylesheet" href="{{assets}}/css/styles.css">
 ```
 
-Results in `dist/foo.html`, with this content:
+Renders to:
 
 ```handlebars
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <title>Foo</title>
-    <link rel="stylesheet" href="public/css/styles.css">
-  </head>
-  <body>
-    ....
-  </body>
-</html>
+<link rel="stylesheet" href="site/public/css/styles.css">
 ```
diff --git a/docs/_verb/options.md b/docs/_verb/options.md
@@ -1,8 +1,28 @@
+{%= apidocs(require('resolve').sync('template'), {
+  dest: "https://github.com/jonschlinkert/template/blob/master/index.js"
+}) %}
+
 # Options API
 
-> Setting and getting options 
+> The Options API exposes methods for setting and getting options in Assemble. 
+
+## Overview
+
+- Options are stored on the `assemble.options` object.
+- Options can be defined and used in any way you need in your projects. 
+- Assemble uses the same API to set [default options][built-in options] for some of assemble's built-in features, such as `layout` and `layoutdir`. Defaults can easily be changed, disabled or overridden.
+
+## Methods
 
-The Options API exposes methods for setting and getting options in Assemble. Assemble uses some options as configuration settings for assemble's built-in features, such as `layout` and `layoutdir`, but options can be defined and used in any way you need in your projects. (see a list of the [built-in options]).
+The following methods are used for managing options in assemble:
+
+- [.option](#option)
+- [.enable](#enable)
+- [.enabled](#enabled)
+- [.disable](#disable)
+- [.disabled](#disabled)
+
+See [related links](#related).
 
 ## .option
 
@@ -24,3 +44,122 @@ assemble.option({
   layout: 'blog'
 });
 ```
+
+### [.option](index.js#L44)
+
+Set or get an option.
+
+* `key` **{String}**: The option name.    
+* `value` **{*}**: The value to set.    
+* `returns` **{*}**: Returns a `value` when only `key` is defined.  
+
+```js
+assemble.option('a', true);
+assemble.option('a');
+//=> true
+```
+
+### [.enable](index.js#L71)
+
+Enable `key`.
+
+* `key` **{String}**    
+* `returns` **{Object}** `Options`: to enable chaining  
+
+**Example**
+
+```js
+assemble.enable('a');
+```
+
+### [.disable](index.js#L89)
+
+Disable `key`.
+
+* `key` **{String}**: The option to disable.    
+* `returns` **{Object}** `Options`: to enable chaining  
+
+**Example**
+
+```js
+assemble.disable('a');
+```
+
+### [.enabled](index.js#L110)
+
+Check if `key` is enabled (truthy).
+
+* `key` **{String}**    
+* `returns`: {Boolean}  
+
+```js
+assemble.enabled('a');
+//=> false
+
+assemble.enable('a');
+assemble.enabled('a');
+//=> true
+```
+
+### [.disabled](index.js#L131)
+
+Check if `key` is disabled (falsey).
+
+* `key` **{String}**    
+* `returns` **{Boolean}**: Returns true if `key` is disabled.  
+
+```js
+assemble.disabled('a');
+//=> true
+
+assemble.enable('a');
+assemble.disabled('a');
+//=> false
+```
+
+### [.hasOption](index.js#L151)
+
+Return true if `options.hasOwnProperty(key)`
+
+* `key` **{String}**    
+* `returns` **{Boolean}**: True if `key` is is on options.  
+
+```js
+assemble.hasOption('a');
+//=> false
+assemble.option('a', 'b');
+assemble.hasOption('a');
+//=> true
+```
+
+### [.isBoolean](index.js#L171)
+
+Return true if `options.hasOwnProperty(key)`
+
+* `key` **{String}**    
+* `returns` **{Boolean}**: True if `key` is is on options.  
+
+```js
+assemble.hasOption('a');
+//=> false
+assemble.option('a', 'b');
+assemble.hasOption('a');
+//=> true
+```
+
+### [.flags](index.js#L184)
+
+* `keys` **{Array}**    
+* `returns`: {Array}  
+
+Generate an array of command line args from
+the given `keys` or all options.
+
+
+## Related
+
+- Learn about [assemble's built-in options][built-in options]
+- Visit [options-cache](https://github.com/jonschlinkert/options-cache) to see all available features.
+
+
+[built-in options](./options-built-in.md)
diff --git a/docs/_verb/tasks.md b/docs/_verb/tasks.md
@@ -0,0 +1,30 @@
+# Tasks
+
+> TODO
+
+## Overview
+
+- 
+
+
+**Examples**
+
+
+```js
+assemble.task('default', function() {
+  assemble.src('templates/*.hbs')
+    .pipe(assemble.dest('dist/'));
+});
+```
+
+**With plugins**
+
+```js
+assemble.task('default', function() {
+  assemble.src('templates/*.hbs')
+    .pipe(plugin1())
+    .pipe(plugin2())
+    .pipe(plugin3())
+    .pipe(assemble.dest('dist/'));
+});
+```
diff --git a/docs/assemble.files.md b/docs/assemble.files.md
@@ -10,8 +10,8 @@ Returns something like:
 
 ```js
 { home: {
-    base: '/site/template/pages/',
-    content: '{{ msg }}',
+    base: '/site/template/',
+    content: 'foo {{ msg }} bar',
     cwd: '/site',
     data: { msg: 'hello world', src: [Object], dest: [Object] },
     options: {},
@@ -21,6 +21,8 @@ Returns something like:
 }}
 ```
 
+**Usage in plugins**
+
 When `files` is used inside a plugin, the stream must be bound to the session via `session.bindEmitter`:
 
 ```js

diff --git a/docs/draft/caching.md b/docs/draft/caching.md
diff --git a/docs/helpers.md b/docs/helpers.md
@@ -2,6 +2,14 @@
 
 > Using helpers in templates
 
+
+## Overview
+
+- Helpers are stored on the `assemble.options` object.
+- Helpers can be defined and used in any way you need in your projects. 
+- Assemble uses the same API to set [default options][built-in options] for some of assemble's built-in features, such as `layout` and `layoutdir`. Defaults can easily be changed, disabled or overridden.
+
+
 ## What are helpers?
 
 Helpers are just regular javascript functions that can be used in templates. Helpers are used to inject or transform data or content. 

diff --git a/docs/built-in-options.md → docs/options-built-in.md b/docs/built-in-options.md → docs/options-built-in.md