From 171d67b5f093d529f99a7f432631cccd97f588bf Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Tue, 11 Apr 2017 09:43:03 -0500 Subject: [PATCH 01/10] initial plugin documentation --- docs/bit-docs/plugins.md | 186 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 183 insertions(+), 3 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 56842e2..cb09007 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -1,8 +1,188 @@ @page plugins Plugins @parent BitDocs 0 +@description The bit-docs plugin system explained, and core plugins. -Here you will find plugins maintained by the bit-docs organization. +@body -Plugins provide core and adjunct functionality. You can write your own plugins if these do not suit your needs. Please share, if you do! +The `bit-docs` plugin system provides hooks that allow you to create custom-generated content specific to your site without the need to modify the `bit-docs` source itself. In this section, you will find plugins maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. Please [let us know]() if you write your own plugins! -Find out more about writing your own plugins **here**. +Here we'll explore the architecture of a typical `bit-docs` plugin. + +## Essentials + +At the very least, a basic `bit-docs` plugin will contain these files: + +- `bit-docs.js` +- `package.json` +- `tags.js` +- `theplugin.js` + +Where `bit-docs.js` and `package.json` are for setup, and `tags.js` or `theplugin.js` might contain actual functionality. + +### Registration + +To use a plugin within a `bit-docs` enabled project, you must tell the project about your plugin. + +In the case of a plugin named `the-plugin`, you would add to a project's `package.json` like: + +```json +{ + "name": "my-project", + ... + "devDependencies": { + "bit-docs": "*" + }, + "bit-docs": { + "dependencies": { + ... + "bit-docs-generate-html": "*", + "the-plugin": "0.0.1" + }, + ... + } +} +``` + +When `bit-docs` attempts to load any such plugin, it looks to require a `bit-docs.js` file from the plugin root, to get the configuration and registration details. This `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. + +A typical `bit-docs.js` will contain basic setup like: + +```js +var tags = require("./tags"); +module.exports = function(bitDocs){ + var pkg = require("./package.json"); + var dependencies = {}; + dependencies[pkg.name] = pkg.version; + + bitDocs.register("html", { + dependencies: dependencies + }); + + bitDocs.register("tags", tags); +} +``` + +This might look intimidating if you're not familiar with the `bit-docs` plugin API, but it's straightforward. + +Let's break it down, starting with that first call to `bitDocs.register`. + +#### Registering front-end dependencies + +The first call to `bitDocs.register` in the code of that example `bit-docs.js` file above is registering code to be loaded on the front-end; plugins typically need to add front-end JavaScript or CSS to the generated website for user interface purposes. The `html` hook actually passes through the `bit-docs` system, and is subsequently handled by the default generator plugin, `bit-docs-generate-html`. + +The way `bit-docs-generate-html` handles this hook is to download your plugin from npm at build time, and then extract code from specific files into the generated website. More on the specifics of this "extraction" later, but first let's dissect the registration code itself. + +You will see this pattern in most of the plugins that need to register front-end dependencies: get the plugin name from the plugin's own `package.json`, and then set that as a key on an empty object with the value set to the plugin's current version, resulting in an object with that familiar npm dependency format: + +```json +{ + "the-plugin": "0.0.1" +} +``` + +Next, the `register` function is called on `bitDocs`, where `bitDocs` is an argument passed into the default `module.exports` function by the `bit-docs` system at runtime. In this example, `the-plugin` is registering itself with the `html` hook. You might also have noticed the `tags` hook but ignore it for now; that registers a back-end dependency, covered in the next section. + +As stated earlier, the `html` hook is not handled by `bit-docs` itself ([look here](https://github.com/bit-docs/bit-docs/blob/master/lib/configure/configure.js#L43-L62) for the hooks `bit-docs` does handle internally). When `bit-docs` encounters a hook that it doesn't handle, it takes the arguments and passes them on to any plugin that might wish to handle that hook, such as `bit-docs-generate-html`. + +The way `bit-docs-generate-html` handles the `html` hook is by calling `bitDocs.handle` in its own `bit-docs.js` file: + +```js +module.exports = function(bitDocs){ + // ... + bitDocs.handle("html", function(siteConfig, htmlConfig) { + // ... + }); +}; +``` + +Handling custom hooks like this will be covered later, but for now just know that's how the default generator plugin `bit-docs-generate-html` will get to handle the `html` hook specified in `the-plugin`. + +Once `bit-docs-generate-html` has downloaded all `dependencies` hooked into `html` by all plugins such as the example `the-plugin`, it will extract the specified front-end code into the generated website. The specified front-end code to extract comes from the `main` value of the downloaded plugin `package.json`. + +In the case of the example plugin `the-plugin`, its `package.json` might look like: + +```json +{ + "name": "the-plugin", + "version": "0.0.1", + "description": "An example plugin", + "main": "theplugin.js", + ... +``` + +In this case, the `main` file is `theplugin.js`. The `main` file of a plugin added to the `html` hook for `bit-docs-generate-html` should contain a `module.export` with whatever code that is intended to run on the front-end of the generated website. + +For instance, `theplugin.js` might look like: + +```js +module.exports = function(){ + alert(document.getElementById("demo").innerHTML); +}; +``` + +To "extract" that code from the `main` file of the plugin and get it into the front-end of the generated website, `bit-docs-generate-html` composites all such front-end code from each registered "dependencies" package and generates the following code: + +```js +/*the-plugin@0.0.1#theplugin*/ +define('the-plugin@0.0.1#theplugin', function (require, exports, module) { + module.exports = function(){ + alert(document.getElementById("demo").innerHTML); + }; +}); +/*bit-docs-site@0.0.1#packages*/ +define('bit-docs-site@0.0.1#packages', function (require, exports, module) { + function callIfFunction(value) { + if (typeof value === 'function') { + value(); + } + return value; + } + module.exports = { + 'the-plugin': callIfFunction(require('the-plugin')) + }; +}); +``` + +You do not necessarily need to concern yourself with the details of such generated code (that's `bit-docs` job after all, to abstract the implementation details of the website away from you); just know that `bit-docs-generate-html` places such code within the generated site in that file `static/bundles/bit-docs-site/static.js`, and that's how `main` specified in a plugin `package.json` gets loaded to the front-end. + +However, we will point out that our other very useful tool, [StealJS](http://stealjs.com), is what enables the use of modules and `define` syntax, and that is also what handles the client-side loading of modules for the generated website as in the code above. + +This file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case of this `the-plugin` example with its `theplugin.js`, the alert message would appear on the initial page load! + +So, to recap with loading front-end depencies, you need to include the `bit-docs-generate-html` plugin to the website project (almost every `bit-docs` enabled website will want to include this plugin), and then simply register the values of your plugin's `package.json` as shown to the `html` hook, making sure to point `main` to a file contianing the code you want to run on the front end! + +##### Adding Less + +If your plugin needs to add some CSS styles to the front-end of the generated website, you can do so by requiring a Less file in the `main` file mentioned above. For example, doing so for `theplugin.js` would look like: + +```js +require("./thestyles.less") + +module.exports = function(){ + alert(document.getElementById("demo").innerHTML); +}; +``` + +With a Less file `thestyles.less` having contents like: + +```css +body { + div { + background: red; + } +} +``` + +Thanks again to [StealJS](http://stealjs.com), those styles will be compiled and loaded to the front-end of the generated website. + +#### Registering back-end dependencies + +TBD + +### Loading a plugin + +TBD + +### Writing a plugin + +TBD From 466f397583e27e19ed87d47989d475799b0a9889 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 15:18:32 -0500 Subject: [PATCH 02/10] Update to plugin docs --- docs/bit-docs/plugins.md | 88 +++++++++++++++++++++++++++------------- 1 file changed, 59 insertions(+), 29 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index cb09007..54c2a95 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -4,26 +4,33 @@ @body -The `bit-docs` plugin system provides hooks that allow you to create custom-generated content specific to your site without the need to modify the `bit-docs` source itself. In this section, you will find plugins maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. Please [let us know]() if you write your own plugins! +The `bit-docs` plugin system provides hooks that allow you to create custom-generated content specific to your site, without the need to modify the `bit-docs` source itself. -Here we'll explore the architecture of a typical `bit-docs` plugin. +In this section, you will find plugins maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. Please [let us know]() if you write your own plugins! -## Essentials +Continue reading, and we'll explore the architecture of a typical `bit-docs` plugin. -At the very least, a basic `bit-docs` plugin will contain these files: +## Essentials of a Plugin + +Every `bit-docs` plugin contains at least these two files: - `bit-docs.js` - `package.json` + +Where `bit-docs.js` and `package.json` are for registering hooks and specifying dependencies, or other configuration, respectively. + +Depending on the the plugin, you might also have files like: + - `tags.js` - `theplugin.js` -Where `bit-docs.js` and `package.json` are for setup, and `tags.js` or `theplugin.js` might contain actual functionality. +Where `tags.js` or `theplugin.js` contain various functionalities of the plugin. -### Registration +## Registering a Plugin -To use a plugin within a `bit-docs` enabled project, you must tell the project about your plugin. +To use a plugin within a `bit-docs` enabled project, you must tell the project about the plugin. -In the case of a plugin named `the-plugin`, you would add to a project's `package.json` like: +In the case of a plugin named `the-plugin`, you would add it to a project's `package.json` like so: ```json { @@ -36,6 +43,7 @@ In the case of a plugin named `the-plugin`, you would add to a project's `packag "dependencies": { ... "bit-docs-generate-html": "*", + ... "the-plugin": "0.0.1" }, ... @@ -43,9 +51,9 @@ In the case of a plugin named `the-plugin`, you would add to a project's `packag } ``` -When `bit-docs` attempts to load any such plugin, it looks to require a `bit-docs.js` file from the plugin root, to get the configuration and registration details. This `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. +When `bit-docs` attempts to load any plugin, it looks to require `bit-docs.js` from the plugin root. The `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. -A typical `bit-docs.js` will contain basic setup like: +A typical `bit-docs.js` will register some hooks, for example: ```js var tags = require("./tags"); @@ -58,7 +66,7 @@ module.exports = function(bitDocs){ dependencies: dependencies }); - bitDocs.register("tags", tags); + bitDocs.register("tags", tags); } ``` @@ -68,11 +76,15 @@ Let's break it down, starting with that first call to `bitDocs.register`. #### Registering front-end dependencies -The first call to `bitDocs.register` in the code of that example `bit-docs.js` file above is registering code to be loaded on the front-end; plugins typically need to add front-end JavaScript or CSS to the generated website for user interface purposes. The `html` hook actually passes through the `bit-docs` system, and is subsequently handled by the default generator plugin, `bit-docs-generate-html`. +You will see this pattern in most `bit-docs` plugins that need to register front-end dependencies: -The way `bit-docs-generate-html` handles this hook is to download your plugin from npm at build time, and then extract code from specific files into the generated website. More on the specifics of this "extraction" later, but first let's dissect the registration code itself. +```js + var pkg = require("./package.json"); + var dependencies = {}; + dependencies[pkg.name] = pkg.version; +``` -You will see this pattern in most of the plugins that need to register front-end dependencies: get the plugin name from the plugin's own `package.json`, and then set that as a key on an empty object with the value set to the plugin's current version, resulting in an object with that familiar npm dependency format: +This simply gets the plugin name and version from `package.json`, and sets that as a key/value pair on an empty object, resulting in that familiar npm dependency format: ```json { @@ -80,9 +92,19 @@ You will see this pattern in most of the plugins that need to register front-end } ``` -Next, the `register` function is called on `bitDocs`, where `bitDocs` is an argument passed into the default `module.exports` function by the `bit-docs` system at runtime. In this example, `the-plugin` is registering itself with the `html` hook. You might also have noticed the `tags` hook but ignore it for now; that registers a back-end dependency, covered in the next section. +Indeed, this object will be passed as an argument to a hook function and used to install this plugin on the front-end (more on this later). -As stated earlier, the `html` hook is not handled by `bit-docs` itself ([look here](https://github.com/bit-docs/bit-docs/blob/master/lib/configure/configure.js#L43-L62) for the hooks `bit-docs` does handle internally). When `bit-docs` encounters a hook that it doesn't handle, it takes the arguments and passes them on to any plugin that might wish to handle that hook, such as `bit-docs-generate-html`. +Next, the `register` function of `bitDocs` is called (where `bitDocs` is an argument passed in by the `bit-docs` system at runtime): + +```js + bitDocs.register("html", { + dependencies: dependencies + }); +``` + +In this example, `the-plugin` is registering itself with the `html` hook. + +As stated earlier, the `html` hook is not handled by `bit-docs` itself ([look here](https://github.com/bit-docs/bit-docs/blob/master/lib/configure/configure.js#L43-L62) for the hooks `bit-docs` does handle internally). When `bit-docs` encounters a hook that it doesn't handle, it takes the arguments and passes them on to any plugin that might wish to handle that hook, such as [`bit-docs-generate-html`](https://github.com/bit-docs/bit-docs-generate-html). The way `bit-docs-generate-html` handles the `html` hook is by calling `bitDocs.handle` in its own `bit-docs.js` file: @@ -95,11 +117,11 @@ module.exports = function(bitDocs){ }; ``` -Handling custom hooks like this will be covered later, but for now just know that's how the default generator plugin `bit-docs-generate-html` will get to handle the `html` hook specified in `the-plugin`. +Handling custom hooks like this will be covered later, but for now just know that's how the generator plugin `bit-docs-generate-html` informs `bit-docs` that it wants to handle any `html` hook, such as the one specified in `the-plugin`. -Once `bit-docs-generate-html` has downloaded all `dependencies` hooked into `html` by all plugins such as the example `the-plugin`, it will extract the specified front-end code into the generated website. The specified front-end code to extract comes from the `main` value of the downloaded plugin `package.json`. +The `bit-docs-generate-html` plugin will download all those `dependencies` on the options objects hooked into `html` by plugins needing to load some dependencies on the front-end, such as `the-plugin`. It will then extract the specified front-end code into the generated website. The JavaScript or styles that `bit-docs-generate-html` loads into the front-end is determined by looking at the `main` value of the `package.json` of the dependency plugins that got downloaded (such as `the-plugin`'s `package.json`). -In the case of the example plugin `the-plugin`, its `package.json` might look like: +In the case of the example plugin, `the-plugin`, its `package.json` might look like: ```json { @@ -110,17 +132,19 @@ In the case of the example plugin `the-plugin`, its `package.json` might look li ... ``` -In this case, the `main` file is `theplugin.js`. The `main` file of a plugin added to the `html` hook for `bit-docs-generate-html` should contain a `module.export` with whatever code that is intended to run on the front-end of the generated website. +In this case, the `main` file is set to `theplugin.js`. This `main` file should contain a `module.export` with the code that is intended to run on the front-end of the generated website. For instance, `theplugin.js` might look like: ```js module.exports = function(){ - alert(document.getElementById("demo").innerHTML); + alert(document.title); }; ``` -To "extract" that code from the `main` file of the plugin and get it into the front-end of the generated website, `bit-docs-generate-html` composites all such front-end code from each registered "dependencies" package and generates the following code: +Here are some low-level details about how `bit-docs-generate-html` does the extraction: + +To "extract" that code from the `main` file of the plugin, and get it into the front-end of the generated website, `bit-docs-generate-html` composites all such front-end code from each registered "dependencies" plugin package, generating something like the following: ```js /*the-plugin@0.0.1#theplugin*/ @@ -143,17 +167,21 @@ define('bit-docs-site@0.0.1#packages', function (require, exports, module) { }); ``` -You do not necessarily need to concern yourself with the details of such generated code (that's `bit-docs` job after all, to abstract the implementation details of the website away from you); just know that `bit-docs-generate-html` places such code within the generated site in that file `static/bundles/bit-docs-site/static.js`, and that's how `main` specified in a plugin `package.json` gets loaded to the front-end. +Notice the alert code has been extracted into this file. + +You do not necessarily need to concern yourself with the details of such generated code (that's `bit-docs` job after all, to abstract such implementation details away from you); just know that `bit-docs-generate-html` places such code within the generated site, in that file: `static/bundles/bit-docs-site/static.js`, and that's how a `main` specified in a plugin `package.json` gets loaded to the front-end website! -However, we will point out that our other very useful tool, [StealJS](http://stealjs.com), is what enables the use of modules and `define` syntax, and that is also what handles the client-side loading of modules for the generated website as in the code above. +We should point out that it's our other tool, [StealJS](http://stealjs.com), enabling the use of "modules" and `define` syntax on the front-end in this case. -This file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case of this `the-plugin` example with its `theplugin.js`, the alert message would appear on the initial page load! +This generated file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case of the `the-plugin` example (with its `theplugin.js` code extracted), the alert message would appear on initial page load! -So, to recap with loading front-end depencies, you need to include the `bit-docs-generate-html` plugin to the website project (almost every `bit-docs` enabled website will want to include this plugin), and then simply register the values of your plugin's `package.json` as shown to the `html` hook, making sure to point `main` to a file contianing the code you want to run on the front end! +So, to recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` as shown for the `html` hook, making sure to point `main` to a file contianing the code you want to run on the front end! ##### Adding Less -If your plugin needs to add some CSS styles to the front-end of the generated website, you can do so by requiring a Less file in the `main` file mentioned above. For example, doing so for `theplugin.js` would look like: +If your plugin needs to add some styling to the front-end of the generated website, you can do so by requiring a Less file in the `main` file mentioned above. + +For example, doing this in `theplugin.js` might look like: ```js require("./thestyles.less") @@ -163,7 +191,7 @@ module.exports = function(){ }; ``` -With a Less file `thestyles.less` having contents like: +Then, create a Less file named `thestyles.less` having contents like: ```css body { @@ -173,7 +201,9 @@ body { } ``` -Thanks again to [StealJS](http://stealjs.com), those styles will be compiled and loaded to the front-end of the generated website. +Now when you generate the website, it should have a red background! + +[StealJS](http://stealjs.com) compiles and loads those styles to the front-end of the generated website. #### Registering back-end dependencies From 6094f44790c94866dc9adda2cdc5efa284863bc0 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 15:30:01 -0500 Subject: [PATCH 03/10] Improve plugin guide intro --- docs/bit-docs/plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 54c2a95..9a6373a 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -6,7 +6,7 @@ The `bit-docs` plugin system provides hooks that allow you to create custom-generated content specific to your site, without the need to modify the `bit-docs` source itself. -In this section, you will find plugins maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. Please [let us know]() if you write your own plugins! +A number of plugins are maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. Continue reading, and we'll explore the architecture of a typical `bit-docs` plugin. From e80dfdc39b1db82062d326f9f20dd2e4cac2eec1 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:21:36 -0500 Subject: [PATCH 04/10] Iterate plugin guide --- docs/bit-docs/plugins.md | 53 +++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 9a6373a..85b8cb7 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -4,9 +4,14 @@ @body -The `bit-docs` plugin system provides hooks that allow you to create custom-generated content specific to your site, without the need to modify the `bit-docs` source itself. +The `bit-docs` plugin system provides hooks that allow you to modify your generated website, without the need to modify `bit-docs` itself. -A number of plugins are maintained by the bit-docs organization; some of these plugins provide core functionality, though all can be replaced if they do not suit your needs. +A number of plugins are maintained by the bit-docs organization. Some of these plugins provide core functionality, and will need to be included with every project, unless they are replaced. Typically you will need a "finder" plugin to pull in files, a "processor" plugin to processes pulled in data, and then a "generator" plugin to generate the output. So, a typical `bit-docs` enabled project will include: + +- [bit-docs-glob-finder] - Finder +- [bit-docs-dev] — Processor +- [bit-docs-js] — Processor +- [bit-docs-generate-html] — Generator Continue reading, and we'll explore the architecture of a typical `bit-docs` plugin. @@ -17,20 +22,20 @@ Every `bit-docs` plugin contains at least these two files: - `bit-docs.js` - `package.json` -Where `bit-docs.js` and `package.json` are for registering hooks and specifying dependencies, or other configuration, respectively. +Where `bit-docs.js` and `package.json` are for registering hooks and specifying dependencies. Depending on the the plugin, you might also have files like: - `tags.js` - `theplugin.js` -Where `tags.js` or `theplugin.js` contain various functionalities of the plugin. +Where `tags.js` or `theplugin.js` might contain various functionalities of the plugin. ## Registering a Plugin To use a plugin within a `bit-docs` enabled project, you must tell the project about the plugin. -In the case of a plugin named `the-plugin`, you would add it to a project's `package.json` like so: +In the case of a plugin named `the-plugin`, you would add it to a website project's `package.json` like so: ```json { @@ -51,7 +56,9 @@ In the case of a plugin named `the-plugin`, you would add it to a project's `pac } ``` -When `bit-docs` attempts to load any plugin, it looks to require `bit-docs.js` from the plugin root. The `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. +When `bit-docs` attempts to load any plugin, it looks to require `bit-docs.js` from the plugin root. + +The `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. A typical `bit-docs.js` will register some hooks, for example: @@ -72,8 +79,6 @@ module.exports = function(bitDocs){ This might look intimidating if you're not familiar with the `bit-docs` plugin API, but it's straightforward. -Let's break it down, starting with that first call to `bitDocs.register`. - #### Registering front-end dependencies You will see this pattern in most `bit-docs` plugins that need to register front-end dependencies: @@ -84,7 +89,7 @@ You will see this pattern in most `bit-docs` plugins that need to register front dependencies[pkg.name] = pkg.version; ``` -This simply gets the plugin name and version from `package.json`, and sets that as a key/value pair on an empty object, resulting in that familiar npm dependency format: +This simply gets the plugin name and version from `package.json`, setting them as a key/value pair on an empty object, resulting in that familiar npm dependency format: ```json { @@ -92,9 +97,9 @@ This simply gets the plugin name and version from `package.json`, and sets that } ``` -Indeed, this object will be passed as an argument to a hook function and used to install this plugin on the front-end (more on this later). +Indeed, this object will be passed as an argument to a hook function, and used to install this plugin on the front-end. -Next, the `register` function of `bitDocs` is called (where `bitDocs` is an argument passed in by the `bit-docs` system at runtime): +Next, the `register` function of `bitDocs` is called (`bitDocs` is an argument passed in by `bit-docs` at runtime): ```js bitDocs.register("html", { @@ -104,7 +109,7 @@ Next, the `register` function of `bitDocs` is called (where `bitDocs` is an argu In this example, `the-plugin` is registering itself with the `html` hook. -As stated earlier, the `html` hook is not handled by `bit-docs` itself ([look here](https://github.com/bit-docs/bit-docs/blob/master/lib/configure/configure.js#L43-L62) for the hooks `bit-docs` does handle internally). When `bit-docs` encounters a hook that it doesn't handle, it takes the arguments and passes them on to any plugin that might wish to handle that hook, such as [`bit-docs-generate-html`](https://github.com/bit-docs/bit-docs-generate-html). +As stated earlier, the `html` hook is not handled by `bit-docs` itself ([look here](https://github.com/bit-docs/bit-docs/blob/master/lib/configure/configure.js#L43-L62) for the hooks `bit-docs` does handle). When `bit-docs` encounters a hook that it doesn't handle, it takes the arguments and passes them along to any plugin that might wish to handle that hook, such as [`bit-docs-generate-html`](https://github.com/bit-docs/bit-docs-generate-html). The way `bit-docs-generate-html` handles the `html` hook is by calling `bitDocs.handle` in its own `bit-docs.js` file: @@ -117,11 +122,11 @@ module.exports = function(bitDocs){ }; ``` -Handling custom hooks like this will be covered later, but for now just know that's how the generator plugin `bit-docs-generate-html` informs `bit-docs` that it wants to handle any `html` hook, such as the one specified in `the-plugin`. +Handling custom hooks like this will be covered later, but just know that's how `bit-docs-generate-html` informs `bit-docs` that it wants to handle any `html` hook (such the one registered in `the-plugin`). -The `bit-docs-generate-html` plugin will download all those `dependencies` on the options objects hooked into `html` by plugins needing to load some dependencies on the front-end, such as `the-plugin`. It will then extract the specified front-end code into the generated website. The JavaScript or styles that `bit-docs-generate-html` loads into the front-end is determined by looking at the `main` value of the `package.json` of the dependency plugins that got downloaded (such as `the-plugin`'s `package.json`). +The `bit-docs-generate-html` plugin will use npm to download any `dependencies` set on those option objects passed as arguments to the `html` hook, and the code that `bit-docs-generate-html` will load into the front-end is determined by looking at the `main` value of the `package.json` of the downloaded dependencies (such as `the-plugin/package.json`). -In the case of the example plugin, `the-plugin`, its `package.json` might look like: +In the case of `the-plugin`, `main` in `package.json` would be set to `theplugin.js`: ```json { @@ -132,9 +137,9 @@ In the case of the example plugin, `the-plugin`, its `package.json` might look l ... ``` -In this case, the `main` file is set to `theplugin.js`. This `main` file should contain a `module.export` with the code that is intended to run on the front-end of the generated website. +This `main` file should have a `module.export` with the code intended to run on the front-end of the generated website. -For instance, `theplugin.js` might look like: +So, `theplugin.js` might contain something like: ```js module.exports = function(){ @@ -142,9 +147,7 @@ module.exports = function(){ }; ``` -Here are some low-level details about how `bit-docs-generate-html` does the extraction: - -To "extract" that code from the `main` file of the plugin, and get it into the front-end of the generated website, `bit-docs-generate-html` composites all such front-end code from each registered "dependencies" plugin package, generating something like the following: +To "extract" that code from the `main` file of the plugin, and get it into the front-end of the generated website, `bit-docs-generate-html` composites all the front-end code from each registered "dependency" plugin package, generating something like the following: ```js /*the-plugin@0.0.1#theplugin*/ @@ -167,15 +170,15 @@ define('bit-docs-site@0.0.1#packages', function (require, exports, module) { }); ``` -Notice the alert code has been extracted into this file. +Notice the alert code has been extracted into this file, as would any other front-end code registered by any other plugins. -You do not necessarily need to concern yourself with the details of such generated code (that's `bit-docs` job after all, to abstract such implementation details away from you); just know that `bit-docs-generate-html` places such code within the generated site, in that file: `static/bundles/bit-docs-site/static.js`, and that's how a `main` specified in a plugin `package.json` gets loaded to the front-end website! +You do not necessarily need to concern yourself with the details of this generated code (that's `bit-docs` job after all, to abstract away such implementation details); just know that `bit-docs-generate-html` places this generated code within the generated site, in that file: `static/bundles/bit-docs-site/static.js`, and that's how a `main` file specified in a plugin `package.json` that registers itelf with the `html` hook gets loaded to the front-end website! -We should point out that it's our other tool, [StealJS](http://stealjs.com), enabling the use of "modules" and `define` syntax on the front-end in this case. +Note: It's our other tool, [StealJS](http://stealjs.com), enabling the use of "modules" and `define` syntax on the front-end. -This generated file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case of the `the-plugin` example (with its `theplugin.js` code extracted), the alert message would appear on initial page load! +The composite file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case the alert message would appear on initial page load! -So, to recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` as shown for the `html` hook, making sure to point `main` to a file contianing the code you want to run on the front end! +To recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` as shown for the `html` hook, making sure to point `main` to a file contianing a `module.exports` with the code you want to run on the front end! ##### Adding Less From 301a970847fd94f8559947f4b6e184cb16e1563d Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:36:04 -0500 Subject: [PATCH 05/10] Reword some plugin guide stuff --- docs/bit-docs/plugins.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 85b8cb7..f3b2178 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -4,16 +4,18 @@ @body -The `bit-docs` plugin system provides hooks that allow you to modify your generated website, without the need to modify `bit-docs` itself. +The `bit-docs` plugin system provides hooks that allow you to modify your generated website. -A number of plugins are maintained by the bit-docs organization. Some of these plugins provide core functionality, and will need to be included with every project, unless they are replaced. Typically you will need a "finder" plugin to pull in files, a "processor" plugin to processes pulled in data, and then a "generator" plugin to generate the output. So, a typical `bit-docs` enabled project will include: +A number of plugins are maintained by the bit-docs organization. Some of these plugins provide core functionality, and will need to be included with every project, unless they are replaced; typically you will need a "finder" plugin to pull in files, a "processor" plugin to processes pulled in data, and then a "generator" plugin to generate the output. -- [bit-docs-glob-finder] - Finder +So, a typical `bit-docs` enabled project will probably include: + +- [bit-docs-glob-finder] — Finder - [bit-docs-dev] — Processor - [bit-docs-js] — Processor - [bit-docs-generate-html] — Generator -Continue reading, and we'll explore the architecture of a typical `bit-docs` plugin. +Here we'll explore the architecture of a typical `bit-docs` plugin. ## Essentials of a Plugin @@ -79,7 +81,7 @@ module.exports = function(bitDocs){ This might look intimidating if you're not familiar with the `bit-docs` plugin API, but it's straightforward. -#### Registering front-end dependencies +### Registering front-end dependencies You will see this pattern in most `bit-docs` plugins that need to register front-end dependencies: @@ -178,9 +180,9 @@ Note: It's our other tool, [StealJS](http://stealjs.com), enabling the use of "m The composite file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case the alert message would appear on initial page load! -To recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` as shown for the `html` hook, making sure to point `main` to a file contianing a `module.exports` with the code you want to run on the front end! +To recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` for the `html` hook, making sure to point `main` to a file contianing a `module.exports` with the code you want to run on the front-end! -##### Adding Less +#### Adding Less If your plugin needs to add some styling to the front-end of the generated website, you can do so by requiring a Less file in the `main` file mentioned above. @@ -206,16 +208,16 @@ body { Now when you generate the website, it should have a red background! -[StealJS](http://stealjs.com) compiles and loads those styles to the front-end of the generated website. +Note: Again, [StealJS](http://stealjs.com) compiles and loads those styles to the front-end of the generated website. -#### Registering back-end dependencies +### Registering back-end dependencies TBD -### Loading a plugin +## Loading a plugin TBD -### Writing a plugin +## Writing a plugin TBD From 4c0157c45166398f7929e21f3fd1ba2f65515ed8 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:42:48 -0500 Subject: [PATCH 06/10] Clean up plugin guide headers --- docs/bit-docs/plugins.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index f3b2178..cfb6d81 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -33,7 +33,7 @@ Depending on the the plugin, you might also have files like: Where `tags.js` or `theplugin.js` might contain various functionalities of the plugin. -## Registering a Plugin +## Using a Plugin To use a plugin within a `bit-docs` enabled project, you must tell the project about the plugin. @@ -58,6 +58,8 @@ In the case of a plugin named `the-plugin`, you would add it to a website projec } ``` +## Registering a Plugin + When `bit-docs` attempts to load any plugin, it looks to require `bit-docs.js` from the plugin root. The `bit-docs.js` file is what bootstraps the plugin within the `bit-docs` system. @@ -213,11 +215,3 @@ Note: Again, [StealJS](http://stealjs.com) compiles and loads those styles to th ### Registering back-end dependencies TBD - -## Loading a plugin - -TBD - -## Writing a plugin - -TBD From 2807f5933d098467ae66c187e0d7fc53c6d3c7dc Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:45:50 -0500 Subject: [PATCH 07/10] Commonly used tags --- docs/bit-docs/plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index cfb6d81..4a6c4b3 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -6,12 +6,12 @@ The `bit-docs` plugin system provides hooks that allow you to modify your generated website. -A number of plugins are maintained by the bit-docs organization. Some of these plugins provide core functionality, and will need to be included with every project, unless they are replaced; typically you will need a "finder" plugin to pull in files, a "processor" plugin to processes pulled in data, and then a "generator" plugin to generate the output. +A number of plugins are maintained by the bit-docs organization. Some of these plugins provide core functionality, and will need to be included with every project, unless they are replaced; typically you will need a "finder" plugin to pull in files, a "processor" plugin to process pulled in data, and then a "generator" plugin to generate the output. So, a typical `bit-docs` enabled project will probably include: - [bit-docs-glob-finder] — Finder -- [bit-docs-dev] — Processor +- [bit-docs-dev] — Commonly used tags - [bit-docs-js] — Processor - [bit-docs-generate-html] — Generator From d9e3bbea5126ac5d88b5db7008c256c7666663dc Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:49:44 -0500 Subject: [PATCH 08/10] Tab to spaces --- docs/bit-docs/plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 4a6c4b3..93f64cd 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -122,7 +122,7 @@ module.exports = function(bitDocs){ // ... bitDocs.handle("html", function(siteConfig, htmlConfig) { // ... - }); + }); }; ``` From 6dbd2b2fc6314031c3332c4cce90997eeffac973 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 16:58:09 -0500 Subject: [PATCH 09/10] Updates --- docs/bit-docs/plugins.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 93f64cd..82ea6dd 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -128,7 +128,7 @@ module.exports = function(bitDocs){ Handling custom hooks like this will be covered later, but just know that's how `bit-docs-generate-html` informs `bit-docs` that it wants to handle any `html` hook (such the one registered in `the-plugin`). -The `bit-docs-generate-html` plugin will use npm to download any `dependencies` set on those option objects passed as arguments to the `html` hook, and the code that `bit-docs-generate-html` will load into the front-end is determined by looking at the `main` value of the `package.json` of the downloaded dependencies (such as `the-plugin/package.json`). +The `bit-docs-generate-html` plugin will use npm to download any `dependencies` set on the option objects passed as arguments to the `html` hook. The code that `bit-docs-generate-html` will load into the front-end is determined by looking at `package.json`'s `main` for the fetched dependency (such as `the-plugin/package.json`). In the case of `the-plugin`, `main` in `package.json` would be set to `theplugin.js`: @@ -141,9 +141,9 @@ In the case of `the-plugin`, `main` in `package.json` would be set to `theplugin ... ``` -This `main` file should have a `module.export` with the code intended to run on the front-end of the generated website. +`main` should have a `module.export` with code intended to run on the front-end of the generated website. -So, `theplugin.js` might contain something like: +So, `theplugin.js` might look something like: ```js module.exports = function(){ @@ -151,7 +151,7 @@ module.exports = function(){ }; ``` -To "extract" that code from the `main` file of the plugin, and get it into the front-end of the generated website, `bit-docs-generate-html` composites all the front-end code from each registered "dependency" plugin package, generating something like the following: +To "extract" that code from the `main` file of the plugin, and get it into the front-end of the generated website, `bit-docs-generate-html` composites all front-end code from each registered dependency: ```js /*the-plugin@0.0.1#theplugin*/ @@ -174,15 +174,17 @@ define('bit-docs-site@0.0.1#packages', function (require, exports, module) { }); ``` -Notice the alert code has been extracted into this file, as would any other front-end code registered by any other plugins. +The alert code has been extracted into this file, as would any other front-end code registered by any other plugins. -You do not necessarily need to concern yourself with the details of this generated code (that's `bit-docs` job after all, to abstract away such implementation details); just know that `bit-docs-generate-html` places this generated code within the generated site, in that file: `static/bundles/bit-docs-site/static.js`, and that's how a `main` file specified in a plugin `package.json` that registers itelf with the `html` hook gets loaded to the front-end website! +You do not necessarily need to concern yourself with the details of this generated code (that's `bit-docs` job after all, to abstract away such implementation details); just know that `bit-docs-generate-html` places this generated code within the generated site, in the file `static/bundles/bit-docs-site/static.js`, and that's how a `main` file specified in a plugin's `package.json` that registers itelf with the `html` hook gets loaded into the front-end website! Note: It's our other tool, [StealJS](http://stealjs.com), enabling the use of "modules" and `define` syntax on the front-end. -The composite file is subsequently loaded on the front-end of the generated website using a normal script tag, and so in the case the alert message would appear on initial page load! +The composite file is loaded on the front-end of the generated website using like a normal script tag by Steal. In this case, that means the alert message would appear on initial page load of the genereted website! -To recap on loading front-end depencies, all you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` for the `html` hook, making sure to point `main` to a file contianing a `module.exports` with the code you want to run on the front-end! +To recap on loading front-end depencies: + +All you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` for the `html` hook, making sure `main` in `package.json` points to a file contianing a `module.exports` with the code you want to run on the front-end! #### Adding Less From 2beb766832d6a7182a7e1f35647a697282825572 Mon Sep 17 00:00:00 2001 From: Joel Kuzmarski Date: Wed, 12 Apr 2017 17:01:14 -0500 Subject: [PATCH 10/10] Wording --- docs/bit-docs/plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/bit-docs/plugins.md b/docs/bit-docs/plugins.md index 82ea6dd..92e632f 100644 --- a/docs/bit-docs/plugins.md +++ b/docs/bit-docs/plugins.md @@ -184,7 +184,7 @@ The composite file is loaded on the front-end of the generated website using lik To recap on loading front-end depencies: -All you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the values of your plugin's `package.json` for the `html` hook, making sure `main` in `package.json` points to a file contianing a `module.exports` with the code you want to run on the front-end! +All you need to do is include the `bit-docs-generate-html` plugin for your website project (almost every `bit-docs` enabled website will want to include this plugin, unless you create your own primary generator plugin), and then simply register the `html` hook with the `name` and `version` values of your plugin's `package.json`, making sure `main` in `package.json` points to a file contianing a `module.exports` with the code you want to run on the front-end! #### Adding Less