diff --git a/CHANGELOG.md b/CHANGELOG.md
deleted file mode 100644
index 3e055bb..0000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Change Log
-
-The **gitbook-plugin-folding-menu** project adheres to [Semantic
-Versioning](http://semver.org/).
-
-Each release is documented on this page *(in addition to the [Github
-Release
-Notes](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases))*,
-and **contains migration instructions**.
-
-## Summary:
-
-Release | What | *When*
----------|-------------------------------------------------|------------------
-[v1.0.0] | Initial Release | *September 7, 2018*
-
-[v1.0.0]: #v100---initial-release-september-7-2018
-
-
-
-
-
-
-
-
-
-
-## v1.0.0 - Initial Release *(September 7, 2018)*
-[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.0)
-•
-[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.0)
-
-**This is where it all began ...**
-
-1. Holy Guacamole Batman! ... _This commit has no parents!!_
diff --git a/README.md b/README.md
index 77a4299..0d37c5b 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,17 @@ one section at a time** _(the active section)_.
[](https://www.npmjs.com/package/gitbook-plugin-folding-menu)
+
+## At a Glance
+
+- [Overview]
+- [Install]
+- [Configuration]
+- [Revision History]
+ * [v1.0.1] - Added Configuration *(September 8, 2018)*
+ * [v1.0.0] - Initial Release *(September 7, 2018)*
+
+
## Overview
The high-level points of interest are:
@@ -39,29 +50,119 @@ This project is a significant improvement on other similar plugins.
## Install
-- Add the `"folding-menu"` plugin to your **book.json** file:
-
- ```js
- {
- "plugins": [
- ... other plugins you may be using
- "folding-menu"
- ]
+1. Add the `"folding-menu"` plugin to your **book.json** file:
+
+ **book.json**
+ ```js
+ {
+ ...
+ "plugins": [
+ ... other plugins you may be using
+ "folding-menu"
+ ]
+ ...
+ }
+ ```
+
+2. Install the plugin using **one** of the following options _(based on your gitbook usage)_:
+
+ - For https://legacy.gitbook.com/ usage, plugins are automatically installed.
+
+ - For local gitbook usage run `gitbook install` to install and prepare
+ all plugins for your books:
+
+ ```shell
+ gitbook install
+ ```
+
+ - For technical users _(ex: open source documentation)_, install the
+ plugin to your **devDependencies** as follows:
+
+ ```shell
+ npm install --save-dev gitbook-plugin-folding-menu
+ ```
+
+
+## Configuration
+
+You may optionally supply the following configuration to this plugin:
+
+
+
+**book.json**
+```js
+{
+ ...
+ "pluginsConfig": {
+ "folding-menu": {
+ "animationDuration": 500,
+ "sticky": true
+ }
}
- ```
+ ...
+}
+```
+
+
+
+- **animationDuration** - The animation duration in mills ... use 0
+ (zero) to disable animation ... **DEFAULT: 400**
+
+- **sticky** - Leave the last section expanded when a the current
+ active section has NO sub-content ... **DEFAULT: false**
+
+
+## Revision History
+
+
+Release | What | *When*
+---------|-------------------------------------------------|------------------
+[v1.0.1] | Added Configuration | *September 8, 2018*
+[v1.0.0] | Initial Release | *September 7, 2018*
+
+
+
+
+
+### v1.0.1 - Added Configuration *(September 8, 2018)*
+
+
+
+[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.1)
+•
+[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.1)
+•
+[Diff](https://github.com/KevinAst/gitbook-plugin-folding-menu/compare/v1.0.0...v1.0.1)
+
+**NOTE**: This release is a **non-breaking change** _(i.e. no API was affected)_.
+
+- This plugin is now configurable _(see: [Configuration])_.
+
+
+
+
+
+
+
+### v1.0.0 - Initial Release *(September 7, 2018)*
+
+
+
+[GitHub Content](https://github.com/KevinAst/gitbook-plugin-folding-menu/tree/v1.0.0)
+•
+[GitHub Release](https://github.com/KevinAst/gitbook-plugin-folding-menu/releases/tag/v1.0.0)
+
+**This is where it all began ...**
-- For https://legacy.gitbook.com/ usage, plugins are automatically installed.
+
-- For local gitbook usage run `gitbook install` to install and prepare
- all plugins for your books:
- ```shell
- gitbook install
- ```
-- For technical users _(ex: open source documentation)_, install the
- plugin to your **devDependencies** as follows:
- ```shell
- npm install --save-dev gitbook-plugin-folding-menu
- ```
+
+[Overview]: #overview
+[Install]: #install
+[Configuration]: #configuration
+[Revision History]: #revision-history
+ [v1.0.1]: #v101---added-configuration-september-8-2018
+ [v1.0.0]: #v100---initial-release-september-7-2018
diff --git a/book/plugin.js b/book/plugin.js
index 16b6bf4..69c0113 100644
--- a/book/plugin.js
+++ b/book/plugin.js
@@ -5,6 +5,23 @@
//***
require(["gitbook", "jQuery"], function(gitbook, $) {
+ // our plugin configuration object
+ // ... optionally defined in client book.json
+ // ... auto defaulted by gitbook as follows:
+ // config: {
+ // animationDuration: 400,
+ // sticky: false
+ // }
+ var config = null;
+
+ // glean plugin configuration on start event
+ gitbook.events.bind('start', function(e, myConfig) {
+ // simply retain in parent scope (for subsequent use)
+ config = myConfig['folding-menu'];
+ diag('start event ... config: ', config);
+ });
+
+
// listen for gitbook "page.change" events
// ... emitted whenever a file.md changes
gitbook.events.bind("page.change", function(e) {
@@ -50,9 +67,10 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
// starts out with leftNav expanded!!!
baselinePriorVisibility($topSections);
- // leave the last expanded section in-tact, when a the current section has NO content
+ // when necessary, leave the last section expanded
// ... by simply no-oping
- if ($activeTopSection.length === 0) {
+ if (config.sticky && // when configured to be sticky -AND-
+ $activeTopSection.length === 0) { // the current active section has NO sub-content
return;
}
@@ -136,8 +154,6 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
// - resulting in a MUCH better visual
function setVisible(elmSection, directive) {
- var animationDelay = 400; // utilize an appropriate animation delay (nice visual)
-
var sectionKey = getSectionKey(elmSection);
var curSectionVisibility = getCurSectionVisibility(sectionKey);
@@ -145,9 +161,9 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
// apply the visibility directive, when needed (based on cached current visibility)
if (directive === 'show') {
- if (curSectionVisibility !== 'show') { // when out-of-sync
- $(elmSection).show(animationDelay); // ... change visiblity WITH animation
- visibilityCache[sectionKey] = 'show'; // ... maintaining our cache
+ if (curSectionVisibility !== 'show') { // when out-of-sync
+ $(elmSection).show(config.animationDuration); // ... change visiblity WITH animation
+ visibilityCache[sectionKey] = 'show'; // ... maintaining our cache
diagMsg += 'SHOWING';
}
else {
@@ -155,9 +171,9 @@ require(["gitbook", "jQuery"], function(gitbook, $) {
}
}
else {
- if (curSectionVisibility !== 'hide') { // when out-of-sync
- $(elmSection).hide(animationDelay); // ... change visiblity WITH animation
- visibilityCache[sectionKey] = 'hide'; // ... maintaining our cache
+ if (curSectionVisibility !== 'hide') { // when out-of-sync
+ $(elmSection).hide(config.animationDuration); // ... change visiblity WITH animation
+ visibilityCache[sectionKey] = 'hide'; // ... maintaining our cache
diagMsg += 'HIDING';
}
else {
diff --git a/package.json b/package.json
index f98b05a..8675eca 100644
--- a/package.json
+++ b/package.json
@@ -1,11 +1,27 @@
{
"name": "gitbook-plugin-folding-menu",
- "version": "1.0.0",
+ "version": "1.0.1",
"description": "GitBook plugin that tames large left-nav menus by visualizing one section at a time",
"main": "index.js",
"engines": {
"gitbook": "*"
},
+ "gitbook": {
+ "properties": {
+ "animationDuration": {
+ "type": "number",
+ "default": 400,
+ "description": "The animation duration in mills ... use 0 (zero) to disable animation ... DEFAULT: 400",
+ "min": 0,
+ "max": 5000
+ },
+ "sticky": {
+ "type": "boolean",
+ "default": false,
+ "description": "Leave the last section expanded when a the current active section has NO sub-content ... DEFAULT: false"
+ }
+ }
+ },
"repository": {
"type": "git",
"url": "https://github.com/KevinAst/gitbook-plugin-folding-menu.git"