Update plugin documentation (#1502)

## Summary

Update Plugin documentation in response to #1499.

* Adds more details about how to include/add a plugin
* Updated schema to match upcoming init_hook improvements
* Adds suggestions on how to structure the plugin directory, along with
an example from mongodb

## How was it tested?

Localhost, also check the preview URL from Vercel below

Author: Lagoja

docs/app/docs/guides/creating_plugins.md

@@ -8,40 +8,33 @@ Plugins make it easier to get started with packages that require additional setu
 
 Before writing a plugin, we recommend reading the [User Documentation](https://www.jetpack.io/devbox/docs/guides/plugins/) on plugins, as well as inspecting and testing a few of the plugins in the [plugin directory](https://github.com/jetpack-io/devbox/tree/main/plugins) of our repo. Note that the plugins in this directory are compiled into the Devbox binary, but your plugin can be sourced from a local directory or from within your project.
 
-
 If you're looking for plugin ideas, check out our [Issues page](https://github.com/jetpack-io/devbox/issues?q=is%3Aissue+is%3Aopen+label%3A%22plugin+request%22) for any user requests.
 
 Before contributing, please consult our [Contributing Guide](https://github.com/jetpack-io/devbox/CONTRIBUTING.md) and [Code of Conduct](https://github.com/jetpack-io/devbox/CODE_OF_CONDUCT.md) for details on how to contribute to Devbox.
 
-### Testing your Plugin
+## Creating a Plugin
 
-1. Create a new `devbox.json` in an empty directory using `devbox init`.
-2. Add your plugin to the `include` section of the `devbox.json` file. Add any expected packages using `devbox add <pkg>`.
-3. Check that your plugin creates the correct files and environment variables when running `devbox shell`
-4. If you are looking for sample projects to test your plugin with, check out our [examples](https://github.com/jetpack-io/devbox/tree/main/examples).
+We recommend organizing your plugin with the following directory structure, where the top-level folder matches the name of your plugin: 
 
-## Plugin Design
+```
+my-plugin/
+├── README.md
+├── plugin.json
+├── config/
+│   ├── my-plugin.conf
+│   └── process-compose.yaml
+└── test/
+    ├── devbox.json
+    └── devbox.lock
+```
 
-Plugins are defined as Go JSON Template files, using the following schema:
+* **README.md** -- Should contain a description of how your plugin works, and what files, variables, and services it adds to Devbox Projects
+* **plugin.json** -- This file is a Go JSON Template that defines your plugin. See the sections below for more detail
+* **config/** -- This folder contains any support or configuration files required by your plugin, as well as the process-compose.yaml for defining services
+* **test/** -- This directory contains an example project for testing your plugin
 
-```json
-{
-  "name": "",
-  "version": "",
-  "readme": "",
-  "env": {
-    "<key>": "<value>"
-  },
-  "create_files": {
-    "<destination>": "<source>"
-  },
-  "init_hook": [
-    "<bash commands>"
-  ]
-}
-```
 
-A plugin can define services by adding a `process-compose.yaml` file in its `create_files` stanza.
+## Plugin Design
 
 ### Plugin Lifecycle
 
@@ -62,6 +55,31 @@ flowchart TD
    H[Start Services]
 ```
 
+### Plugin.json Schema
+
+Plugins are defined as Go JSON Template files, using the following schema:
+
+```json
+{
+  "name": "",
+  "version": "",
+  "readme": "",
+  "env": {
+    "<key>": "<value>"
+  },
+  "create_files": {
+    "<destination>": "<source>"
+  },
+  "shell": {
+    "init_hook": [
+      "<bash commands>"
+    ]
+  }
+}
+```
+
+A plugin can define services by adding a `process-compose.yaml` file in its `create_files` stanza.
+
 ### Template Placeholders
 
 Devbox's Plugin System provides a few special placeholders that should be used when specifying paths for env variables and helper files:
@@ -108,9 +126,11 @@ Will copy the Caddyfile in the `plugins/caddy` folder to `devbox.d/caddy/Caddyfi
 
 You should use this to copy starter config files or templates needed to run the plugin's package.
 
-#### `init_hook` *string | string[]*
+#### `shell.init_hook` *string | string[]*
+
+A single `bash` command or list of `bash` commands that should run before the user's shell is initialized. 
 
-A single `bash` command or list of `bash` commands that should run before the user's shell is initialized. This will run every time a shell is started, so you should avoid any resource heavy or long running processes in this step.
+This will run every time a shell is started, so you should avoid any resource heavy or long running processes in this step.
 
 ### Adding Services
 
@@ -120,6 +140,39 @@ Plugins can add services to a user's project by adding a `process-compose.yaml`
 
 See the process compose [docs](https://github.com/F1bonacc1/process-compose) for details on how to write define services in `process-compose.yaml`. You can also check the plugins in this directory for examples on how to write services.
 
+## Testing your Plugin
+
+Testing plugins can be done using an example Devbox project. Follow the steps below to create a new test project
+
+1. Create a new `devbox.json` in an empty directory using `devbox init`.
+2. Add your plugin to the `include` section of the `devbox.json` file. 
+2. Add any expected packages using `devbox add <pkg>`.
+3. Check that your plugin creates the correct files and environment variables when running `devbox shell`
+4. If you are looking for sample projects to test your plugin with, check out our [examples](https://github.com/jetpack-io/devbox/tree/main/examples).
+
+
+## Example: MongoDB
+
+The plugin.json below sets the environment variables and config needed to run MongoDB in Devbox. You can view the full example at 
+
+```json
+{
+  "name": "mongodb",
+  "version": "0.0.1",
+  "readme": "Plugin for the [`mongodb`](https://www.nixhub.io/packages/mongodb) package. This plugin configures MonogoDB to use a local config file and data directory for this project, and configures a mongodb service.",
+  "env": {
+    "MONGODB_DATA": "{{.Virtenv}}/data",
+    "MONGODB_CONFIG": "{{.DevboxDir}}/mongod.conf"
+  },
+  "create_files": {
+    "{{.Virtenv}}/data": "",
+    "{{.Virtenv}}/process-compose.yaml": "config/process-compose.yaml",
+    "{{.DevboxDir}}/mongod.conf": "config/mongod.conf"
+  }
+}
+
+```
+
 ## Tips for Writing Plugins
 
 * Only add plugins for packages that require configuration to work with Devbox.

docs/app/docs/guides/plugins.md

@@ -4,9 +4,22 @@ title: Using Plugins
 
 This doc describes how to use Devbox Plugins with your project. **Plugins** provide a default Devbox configuration for a Nix package. Plugins make it easier to get started with packages that require additional setup when installed with Nix, and they offer a familiar interface for configuring packages. They also help keep all of your project's configuration within your project directory, which helps maintain portability and isolation.
 
-If a plugin is available for your package, it will activate when you install the plugin using `devbox add <package name>`.
+## Using Plugins
+
+### Built-in PLguins
+
+If you add one of the packages listed above to your project using `devbox add <pkg>`, Devbox will automatically activate the plugin for that package.
+
+You can also explicitly add a built-in plugin in your project by adding it to the [`include` section](../configuration.md#include) of your `devbox.json` file. For example, to explicitly add the plugin for Nginx, you can add the following to your `devbox.json` file:
+
+```json
+{
+  "include": [
+    "plugin:nginx"
+  ]
+}
+```
 
-## Current Plugins
 Built-in plugins are available for the following packages. You can activate the plugins for these packages by running `devbox add <package_name>`
 
 * [Apache](../devbox_examples/servers/apache.md) (apacheHttpd)
@@ -20,20 +33,25 @@ Built-in plugins are available for the following packages. You can activate the
 * [Pip](../devbox_examples/languages/python.md) (python39Packages.pip, python310Packages.pip, python311Packages.pip...)
 * [Ruby](../devbox_examples/languages/ruby.md)(ruby, ruby_3_1, ruby_3_0...)
 
-Our team is rapidly adding new plugins to Devbox. If you want to request a plugin, please file an issue in the Devbox Repo.
 
-## Using Plugins
+### Local PLugins
 
-If you add one of the packages listed above to your project using `devbox add <pkg>`, Devbox will automatically activate the plugin for that package.
+You can also [define your own plugins](./creating_plugins.md) and use them in your project. To use a local plugin, add the following to the `include` section of your devbox.json:
 
-You can also explicitly add a plugin in your project by adding it to the [`includes` section](../configuration.md#includes) of your `devbox.json` file. For example, to explicitly add the plugin for Nginx, you can add the following to your `devbox.json` file:
+```json
+  "include": [
+    "path:./path/to/plugin.json"
+  ]
+```
+
+### Github Hosted Plugins
+
+Sometimes, you may want to share a plugin across multiple projects or users. In this case, you provide a Github reference to a plugin hosted on Github. To install a github hosted plugin, add the following to the include section of your devbox.json
 
 ```json
-{
-  "includes": [
-    "plugin:nginx"
+  "include": [
+    "github:<org>/<repo>?dir=<plugin-dir>"
   ]
-}
 ```
 
 ## An Example of a Plugin: Nginx