Add basic Docusaurus structure

.gitignore

@@ -20,3 +20,13 @@ _book
 # config
 config/*.yaml
 !config/default.yaml
+
+# docusaurus
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

.istanbul.yml

@@ -2,7 +2,7 @@ verbose: false
 instrumentation:
     root: .
     default-excludes: true
-    excludes: []
+    excludes: ['**/website/**']
     embed-source: false
     variable: __coverage__
     compact: true

docs/advanced.md

@@ -0,0 +1,9 @@
+---
+id: advanced
+title: Advanced
+sidebar_label: Advanced
+---
+
+This section covers more "advanced" topics around how to iterate on your components/component data and how to publish your content to a wider audience leveraging outside networks by turning manipulating component data into different formats beyond JSON & HTML. 
+
+* [Data Versioning (Upgrades)](data_versioning)

docs/bootstrapping.md

@@ -0,0 +1,43 @@
+---
+id: bootstrap
+title: Bootstrapping
+sidebar_label: Bootstrapping
+---
+
+Bootstrapping is the process by which Amphora will look for specific data in your implementation to add to the database. This process runs _EVERYTIME_ the server restarts.
+
+Whenever the process first starts up, Amphora will look into each component directory and each site directory for a `bootstrap.(yml|yaml)` file. This YAML file will be converted into JSON and then the values will be written to the database for each site.
+
+## Why is this necessary?
+
+Bootstrapping is a great time for taking care of two actions:
+
+* Adding default data to a component
+* Adding component instances to the database _that will never change_ from user input
+
+## Skipping Bootstrapping
+
+As of [Amphora 4.2.0](https://github.com/clay/amphora/releases/tag/v4.2.0) the bootstrapping process can be skipped. This is useful when developing server-side services for your implementation as it allows for more rapid startups on larger Clay instances, but this can be dangerous.
+
+As mentioned above, bootstrapping is great for seeding the default data for a component or site. If bootstrapping is turned off and you add a new component to your instance, the default data will not be added to your local database. For this reason, it's encouraged to only use this feature when you know you won't need the bootstrap process to run **and never in production environments**.
+
+To turn off bootstrapping, simply pass the `bootstrap` property into Amphora at instantiation time with a `false` value:
+
+```javascript
+amphora({
+  // ...some other args
+  bootstrap: false
+})
+```
+
+### Default Data
+
+Since components and the data they hold will change and grow \(or shrink\) over time, it's necessary to update the default data that a component is created with anytime the server restarts. By including a bootstrap file in each component directory, you'll be able to make sure that changes to all aspects of the component can be changed within a single directory and that every time the server restarts you'll be working with the default data you expect.
+
+### Slow/Never Changing Component Instances
+
+Bootstrapping is also very handy for adding values which a user should never be able to change in the GUI. An example of this might be an ID for an analytics service. Since you would always want to have a reliable component instance to use while not allowing users to easily change this value, you might choose to have this in a `bootstrap.(yml|yaml)` file in your site's directory. If a user ever does modify a component instance that is created in this file, simply restarting the server will reset the value.
+
+## Word of Caution
+
+The affordances around bootstrapping mean that you can have a `bootstrap.(yml|yaml)` file in each site and each component. At startup time Amphora will try to read all of these and write the values to the database. Because of this, the more bootstrap files you have, the longer the startup time will be.

docs/building-renderers.md

@@ -0,0 +1,28 @@
+---
+id: building-renderers
+title: Building Custom Renderers
+sidebar_label: Building Custom Renderers
+---
+
+The docs address the renderer API as of Amphora v6.x.
+
+A custom renderer can do anything your needs might require when it comes to transforming JSON data from Amphora. All that is required is that your renderer export a `render` function. This function will receive the arguments described below:
+
+* `data` \(Object\): The composed data for the page or component. This data will have passed through complete data composition, including `model.js` files and renderer specific models. This is the data you'll send to your templating language or formatting logic.
+* `meta` \(Object\): This object contains three crucial properties:
+  * `locals` \(Object\): The [Express locals object](https://expressjs.com/en/api.html#res.locals) that has also been annotated by Amphora. This is the same `locals` object passed to component's `model.js` files during composition.
+  * `_ref` \(String\): This is the uri that was requested to be rendered. If you're rendering a `page` or an Express route, this will be the page uri. If you're rendering a component directly, this will be the component's uri.
+  * `_layoutRef` \(String\): This is only provided when rendering a `page` and its value corresponds to the `layout` uri on the page. This is needed for finding the root template when rendering with different templating languages, such as Handlebars.
+* `res` \(Object\): Simply the [Express Response](https://expressjs.com/en/4x/api.html#res) object. This means **it is the responsibility of the renderer to terminate the response**.
+
+An example renderer:
+
+```javascript
+module.exports.render = function (state, res) {
+  var htmlResponse = ...; // Use state object to construct some HTML response..
+
+  res.html(htmlResponse);
+};
+```
+
+Having access to the Express Response object \(`res`\) means a renderer can attach custom headers, choose the response type and any other task you might need.

docs/event_bus.md

@@ -0,0 +1,63 @@
+---
+id: event-bus
+title: Event Bus
+sidebar_label: Event Bus
+---
+
+As of Amphora version `6.6.0` the option of using [Redis as an event bus](https://redis.io/topics/pubsub) has been introduced. This event bus is intended to make it easier to a destructure a Clay instance and supporting platform packages \(i.e. Amphora Search\). By default the Bus module is not instantiated. Only by setting the [Redis Bus Host env var](event-bus#redis-bus-host) will the Bus module be active.
+
+The Event Bus is also intended to replace the plugin system in the next major version of Amphora \(v7\). On top of replacing the plugin system, the event bus will see some small changes to the payload of certain events as the plugin system is rearchitected. The end goal is to expose specific hooks in the Amphora lifecycle to the Bus as quickly as possible.
+
+## Bus Topics
+
+The following topics are published to the bus by Amphora:
+
+* `clay:publishLayout`
+* `clay:publishPage`
+* `clay:createPage`
+* `clay:unschedulePage`
+* `clay:schedulePage`
+* `clay:unpublishPage`
+* `clay:save`
+* `clay:delete`
+
+## Configuring the Bus
+
+The Bus module has two configurations options which are both controlled by environment variables.
+
+### Redis Bus Host
+
+As mentioned, the Bus module is turned off by default. Only by setting the `CLAY_BUS_HOST` env var to a valid Redis url \(`redis://<HOST>:<PORT>`\) will the module be instantiated and events will be published to the instance.
+
+### Namespace
+
+By default, all topics published to the Bus are namespaced using `clay`, i.e. `clay:<ACTION>`. This namespace can be configured by the env var `CLAY_BUS_NAMESPACE`. For example, setting `CLAY_BUS_NAMESPACE` to a value of `mysite` will publish all events as `mysite:<ACTION>`.
+
+## Subscribing To The Bus
+
+Provided you have setup Amphora to pub to a Redis instance, the following code will subscribe to all events from Clay using the [`redis`](https://www.npmjs.com/package/redis) NPM module.
+
+```javascript
+'use strict';
+
+var redis = require('redis'),
+  SUBSCRIBER = redis.createClient(process.env.CLAY_BUS_HOST),
+  CLAY_TOPICS = [
+    'publishLayout',
+    'publishPage',
+    'unpublishPage',
+    'createPage',
+    'schedulePage',
+    'unschedulePage',
+    'save',
+    'delete'
+  ];
+
+for (let i = 0; i < CLAY_TOPICS.length; i++) {
+  SUBSCRIBER.subscribe(`clay:${CLAY_TOPICS[i]}`);
+}
+
+SUBSCRIBER.on('message', (channel, payload) => {
+  console.log(`Channel: ${channel}\n\n\n${payload}`);
+});
+```

docs/glossary-docs.md

@@ -0,0 +1,16 @@
+---
+id: glossary-docs
+title: Glossary
+sidebar_label: Glossary
+---
+## bootstrap
+
+An instantiation argument that defaults to `true`. If set to `false`, the internal [bootstrap](bootstrap) process will be skipped.
+
+## locals.publishUrl
+
+Property that only is available to components during the save of an `@published` instance of a component. This value is determined by whatever url is determined during [publishing](publish#setting-publish-rules).
+
+## _version
+
+A data property managed by Amphora when using the [Data Versioning](data_versioning) feature. This property should not be overwritten to by any `model.js` or external source. If it is, data upgrades will be re-run. Please see the _Data Versioning_ page for more information.

docs/install.md

@@ -0,0 +1,41 @@
+---
+id: install
+title: Instantiation Arguments
+sidebar_label: Instantiation Arguments
+---
+
+The most basic Amphora instantiation might look something like the following code:
+
+```javascript
+const express = require('express'),
+  amphora = require('amphora'),
+  app = express();
+
+
+amphora({
+  app: app // An Express instance
+})
+.then(function (router) {
+  router.listen(port, ip);
+  console.log(`Clay listening on ${ip}:${port}`);
+})
+.catch(function (error) {
+  console.error(error);
+});
+```
+
+Here we create a new Express app, pass it into Amphora and then Amphora will return an Express instance that has been modified with Clay core routes for each site you have created. Once that Express instance is returned \(`router` in this example\), we call the `listen` function, [just like an Express app would](http://expressjs.com/en/api.html#app.listen).
+
+Assuming you have configured your sites properly and have some components, you'll now be able to access any Clay core routes and any data included in [internal bootstrap files](bootstrap) for components and sites will have been added.
+
+## Instantiation Arguments
+
+At instantiation time Amphora accepts a config object which contains properties that affect everything from user sessions to plugins for enhanced functionality. Below is a quick list of arguments with references to further documentation resources on the subjects.
+
+* `app`: an Express instance. If one is not passed in, Amphora will create one during startup. The advantage of passing an instance into Amphora is the ability to add any middleware or other configuration necessary for your specific setup.
+* `providers`: an Array of strings which correspond to the supported authentication services in Amphora: `apikey`, `ldap`, `google`, `slack`, and `twitter`.
+* `sessionStore`: used for session management with user sessions when a provider is configured. For more information see the [Authentication](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/authentication.md) page.
+* `renderers`: an Object that references modules that can be used to transform component data into different formats. For example, [Amphora HTML](https://github.com/clay/amphora-html) is a module that renders component data to HTML using Handlebars templates. Renderers abide by an API that Amphora sets forth. The `renderers` Object should contain properties whose names correspond to request extensions and whose properties are the handlers for those extensions. A `default` property is used to specify the renderer to be used when no extension is specified in a request. For more information, see the [Renderers](building-renderers) documentation.
+* `plugins`: an Array of Objects that have handlers for different plugin hooks that Amphora exposes. Different hooks are exposed for the startup, request and publish life cycles. For more information see the [Plugins](https://github.com/clay/amphora/tree/3a300d4ec7af113afd102b4506e7566eb617c9c8/docs/lifecycle/startup/plugins.md) page.
+* `env`: an accommodation for renderers to expose environment variables used in `model.js` files on the client-side for [Kiln](https://github.com/clay/clay-kiln). These are only rendered in edit mode for a page. For a more thorough understanding of when/how these values are gathered and used, please see the [Component Models](renderer-models) documentation.
+* `bootstrap`: a Boolean value which defaults to `true`. When set to `false` the internal [bootstrapping process](bootstrap#skipping-bootstrapping) will be skipped entirely. **It's advised not to set the value to** `false` **for production instances.**

docs/introduction.md

@@ -0,0 +1,119 @@
+---
+id: intro
+title: Introduction
+sidebar_label: Introduction
+---
+
+![illustration of an amphora](/amphora/img/amphora-logo.svg)
+
+_"A new way to organize, edit, and deliver the web, one component at a time."_
+
+Powering [New York Magazine](http://nymag.com/), [Vulture](http://www.vulture.com/), [The Cut](https://www.thecut.com/), [Grub Street](http://www.grubstreet.com/).  
+Created by New York Media.
+
+## Table of Contents
+
+* [Introduction](#introduction)
+* [Installation](#installation)
+* [Usage](#usage)
+* [Contribution](#contribution)
+* [Advanced Topics](#advanced-topics)
+
+## Introduction
+
+Amphora is a mixin for [Express](https://github.com/strongloop/express) that:
+
+* Composes components into renderable pages
+* Uses any key-value store of your choice \(e.g., Mongo, Redis, LevelDB, etc.\)
+* Provides an API for managing instances of components, uris, and pages
+
+[Components are reusable, configurable, self-contained bits of the web.](https://docs.clayplatform.com/docs/components)
+
+Amphora is a core part of New York Media's Clay project, an open-source content management system.
+
+It follows semver and is stable as of `v1.0.0`.
+
+## Installation
+
+```text
+npm install --save amphora
+```
+
+## Usage
+
+Clay separates concerns into two main areas: components and sites. Create two new directories in your project:
+
+```text
+/components  (where your custom components live)
+/sites       (for site-specific settings, routes, and assets)
+```
+
+In your project's main server file \(e.g. `app.js`\), instantiate a new Amphora instance.
+
+```javascript
+var amphora = require('amphora'),
+  port = process.env.PORT || 3000;
+
+return amphora()
+  .then(function (server) {
+    server.listen(port);
+  });
+```
+
+For additional configuration, you may pass in an Express app/router. You can also override the default templating engine\(s\) with your own.
+
+```javascript
+var app = require('express')(),
+  amphora = require('amphora'),
+  amphoraHtml = require('amphora-html'),
+  port = process.env.PORT || 3000,
+  env;
+
+// add project-specific settings to your app
+app.set('strict routing', true);
+app.set('trust proxy', 1);
+
+// add custom settings to your templating engine
+env.addGlobal('projectName', process.env.PROJECT_NAME);
+
+return amphora({
+  app: app,
+  renderers: {
+    default: 'html',
+    html: amphoraHtml
+  }
+}).then(function (server) {
+  server.listen(port);
+});
+```
+
+### How to create a component
+
+Components in Clay have the following structure:
+
+```text
+/component-name     unique name of your component
+    template.handlebars   your template
+    schema.yml            describes how the component's data is edited
+```
+
+All of these files are optional.
+
+### How to create a template
+
+The template you create is dependent on whichever renderer you'd like to use. The Clay Core team supports an [HTML renderer](https://github.com/clay/amphora-html) using [Handlebars](http://handlebarsjs.com/) template, but the choice is yours. Either request a renderer or build one on your own!
+
+### How to create a schema
+
+[Kiln](https://github.com/nymag/clay-kiln) uses a component's schema.yml to determine how it is edited.
+
+## Contribution
+
+Fork the project and submit a PR on a branch that is not named `master`. We use linting tools and unit tests, which are built constantly using continuous integration. If you find a bug, it would be appreciated if you could also submit a branch with a failing unit test to show your case.
+
+## Advanced Topics
+
+* [New Concepts For Developers and Designers](https://github.com/nymag/amphora/wiki#for-developers-and-designers)
+* [Bootstrapping Data](bootstrap)
+* [Routing](routes)
+* [Plugins](publish)