docs: adds documentation for creating add-ons and a list of official …

…add-ons (#92)

docs/.vuepress/config.js

@@ -144,6 +144,10 @@ module.exports = {
       {
         text: "FAQ's",
         link: '/faqs/'
+      },
+      {
+        text: "Add-on's",
+        link: '/addons/creating-addons'
       }
     ],
     sidebar: {
@@ -170,6 +174,16 @@ module.exports = {
           ],
         },
       ],
+      '/addons/': [
+        {
+          title: "Add-on's",
+          collapsable: false,
+          children: [
+            'creating-addons',
+            'official-addons',
+          ],
+        },
+      ],
     },
   },
 

docs/addons/creating-addons.md

@@ -0,0 +1,53 @@
+# Creating Add-on's
+
+One of the core tenets of Adze is to **not do too much**. This means that the core functionality of Adze is to provide the user with the ability to have control over their logs, how they are shaped, and to be able to listen to their logs and do with the log data as they please. Anything resembling transporting log data to files, API's, or databases is purposefully omitted from the core. However, because of Adze [log listeners](../guide/shed-concepts.md#listeners), there is opportunity for add-on packages to provide simple solutions for handling log data transports and various other solutions.
+
+## Best Practices
+
+When creating add-on's for Adze your primary interface should be wrapping a [log listener](../guide/shed-concepts.md#listeners). By wrapping a log listener you can intercept the [log data](../guide/data.md#label-data-object) and [log render](../guide/data.md#log-render) and act upon it. To do this, your add-on should export a function that takes a callback function as a parameter and then executes that callback function at a later time and forwards the **log data** and **log render** to it as parameters. Let's take a look at an example.
+
+## Add-on Example
+
+Let's first create our wrapper function that our add-on will expose.
+
+#### my-addon.js
+
+```javascript
+// We'll create an exported function that takes a callback as a parameter
+// and sets a default to an empty anonymous function.
+export function MyAddon(cb = () => {}) {
+  // Our wrapper will return a log listener callback function that
+  // accepts log data and a log render.
+  return (data, render) => {
+    // Do stuff with the log data and log render
+
+    // Then make sure to execute the user specified callback before finishing.
+    cb(data, render);
+  };
+}
+```
+
+#### my-app.js
+
+```javascript
+import { adze, createShed } from 'adze';
+
+// Now, in our app, we'll import the wrapper function we created above.
+import { MyAddon } from './my-addon.js';
+
+const shed = createShed();
+
+// Now, to use the add-on, I'll wrap my log listener callback function with
+// the MyAddon wrapper. We'll target all logs to use this add-on.
+shed.addListener('*', MyAddon((data, render) => {
+  // Do normal log listener stuff here...
+}));
+
+// Or alternatively, since we specified an empty anonymous function 
+// as the default parameter of our add-on, we can call it empty.
+shed.addListener('*', MyAddon());
+
+adze().log('This log will be intercepted by our add-on!');
+```
+
+Following the pattern above allows your add-on to operate on log data and log renders while also giving control to the end-user over which logs it wants your add-on to target.

docs/addons/official-addons.md

@@ -0,0 +1,16 @@
+# Official Add-on's
+
+The following list contains add-on's that are officially supported by core Adze contributors and are maintained under the [`@adze` npm organization namespace](). We hope that over time this list will grow and hopefully community created add-on's can be adopted by the official organization.
+
+---
+
+## @adze/security-validator
+
+This project is a plugin for the Adze logging library to provide tools for ensuring proper context is applied to logs that are meant to record security events such as access events and authentication events.
+
+This library exposes some opinionated interfaces and a log listener factory for validating your security event logs.
+
+|             | Location                                                                                                         |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| Source Code | [https://github.com/AJStacy/adze-security-validator](https://github.com/AJStacy/adze-security-validator)         |
+| npm         | [https://www.npmjs.com/package/@adze/security-validator](https://www.npmjs.com/package/@adze/security-validator) |