Permalink
Browse files

add some draft docs

  • Loading branch information...
1 parent 4a8bbc2 commit 213997f87425aac9f18a042d900bfc3c41facfc3 @jonschlinkert jonschlinkert committed Jul 29, 2016
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -0,0 +1,65 @@
+---
+title: Plugins
+related:
+ api: []
+ doc: []
+ repo: ['generate']
+---
+
+A plugin is function that takes an instance of `Assemble` and is registered with the `.use` method.
+
+Enhandced plugin functionality is introduced to assemble by the [base-plugins][] plugin. Visit the [base-plugins][] GitHub repository for addtional details and API documentation.
+
+**Heads up!**
+
+Most or all of the code examples in this document assume the following code exists first:
+
+```js
+var assemble = require('assemble');
+var app = assemble();
+```
+
+### .use
+
+The `.use` method is used for registering plugins that should be immediately invoked.
+
+**Example**
+
+```js
+function plugin(app) {
+ // "app" and "this" both expose the instance of assemble we created above
+}
+
+app.use(plugin);
+```
+
+Once a plugin is invoked, it will not be called again.
+
+### .run
+
+If a plugin returns a function after it's invoked by `.use`, the function will be pushed onto an array allowing it to be called again by the `.run` method.
+
+**Example**
+
+```js
+function plugin(app) {
+ // "app" and "this" both expose the instance of assemble we created above
+ return plugin;
+}
+
+app.use(plugin);
+```
+
+We can now run all plugins that were pushed onto the `.fns` array on any arbitrary object:
+
+```js
+var obj = {};
+app.run(obj);
+```
+
+Additionally:
+
+* If `obj` has a `.use` method, it will be used on each plugin (e.g. `obj.use(fn)`). Otherwise `fn(obj)`.
+* If the plugin returns a function again and `obj` has a `.run` method, the plugin will be pushed onto the `obj.fns` array
+
+This can continue indefinitely as long as the plugin returns a function and the receiving object has `.use`/`.run` functions.
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -0,0 +1,44 @@
+---
+title: Why Assemble?
+---
+
+> Why should I use Assemble, instead of X?
+
+## Context
+
+Assemble gives you more granular control over context and all of the stages in the [render cycle](#render-cycle) than **any** other solution.
+
+Getting context right isn't a nice-to-have, it's a necessity. Despite being a necessity, since context handling can be complex to manage, must static site generators avoid it altogether and tell you to do it.
+
+**Related resources**
+
+- [assemble/context-workshow](https://github.com/assemble/context-workshop): explains how context is created, as well as where, when and why the context works the way it does at each point in the render cycle.
+
+## Base
+
+Assemble is built on [base][], which comes with a number of advantages:
+
+1. If you know how to use assemble, you will know how to use other applications built on `base`, such as [verb][], [generate][] and [update][].
+1. [Plugin system](#plugin-ecosystem)
+
+## Plugin ecosystem
+
+Since assemble is built with [base][], plugin conventions make it easy to create, publish and share plugins with other applications. For example:
+
+* All [base plugins](https://www.npmjs.com/browse/keyword/baseplugin) can be used with assemble
+* Most [verb plugins](https://www.npmjs.com/browse/keyword/verbplugin) can be used with assemble
+* Most [update plugins](https://www.npmjs.com/browse/keyword/updateplugin) can be used with assemble
+* Most [generate plugins](https://www.npmjs.com/browse/keyword/generateplugin) can be used with assemble
+
+**Related resources**
+
+- [plugins docs](docs/plugins.md).
+
+## Expressive API
+
+Assemble has a functional, imperative API that is powerful and easy to use.
+
+
+## Enforce consistent design
+
+Facilitates the use of _modular, encapsulated components_ in your markup, like pages, partials and layouts, resulting in consistent design across your projects.

0 comments on commit 213997f

Please sign in to comment.