From b4b483c3477e21b4a3fdeb602a8bfe64520e9dfe Mon Sep 17 00:00:00 2001 From: Kevin Bridges Date: Sat, 8 Sep 2018 12:56:15 -0500 Subject: [PATCH 1/5] migrate revision history DIRECTLY into README (for visibility in gitbook search) --- CHANGELOG.md | 61 ---------------------------------------------------- README.md | 33 ++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 61 deletions(-) delete mode 100644 CHANGELOG.md 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..e436020 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,15 @@ one section at a time** _(the active section)_. [![NPM Version Badge](https://img.shields.io/npm/v/gitbook-plugin-folding-menu.svg)](https://www.npmjs.com/package/gitbook-plugin-folding-menu) + +## At a Glance + +- [Overview](#overview) +- [Install](#install) +- [Revision History](#revision-history) + * [v1.0.0] - Initial Release *(September 7, 2018)* + + ## Overview The high-level points of interest are: @@ -65,3 +74,27 @@ This project is a significant improvement on other similar plugins. ```shell npm install --save-dev gitbook-plugin-folding-menu ``` + +## Revision History + + +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)* + + From e122a20d5d57f6898d95857693e0ce3308a44ad6 Mon Sep 17 00:00:00 2001 From: Kevin Bridges Date: Sat, 8 Sep 2018 13:15:40 -0500 Subject: [PATCH 2/5] setup version 1.0.1 for next2 branch --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++---- package.json | 2 +- 2 files changed, 45 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e436020..87032ed 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,11 @@ one section at a time** _(the active section)_. ## At a Glance -- [Overview](#overview) -- [Install](#install) -- [Revision History](#revision-history) +- [Overview] +- [Install] +- [Configuration] +- [Revision History] + * [v1.0.1] - Added Configuration *(September 8, 2018)* * [v1.0.0] - Initial Release *(September 7, 2018)* @@ -75,17 +77,44 @@ This project is a significant improvement on other similar plugins. npm install --save-dev gitbook-plugin-folding-menu ``` + +## Configuration + +TODO: ?? document configuration + + + ## Revision History Release | What | *When* ---------|-------------------------------------------------|------------------ +[v1.0.1] | Added Configuration | *September 8, 2018* [v1.0.0] | Initial Release | *September 7, 2018* -[v1.0.0]: #v100---initial-release-september-7-2018 + +### v1.0.1 - Added Configuration *(September 8, 2018)* + + + + + + ### v1.0.0 - Initial Release *(September 7, 2018)* @@ -98,3 +127,14 @@ Release | What | *When* **This is where it all began ...** + + + + + +[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/package.json b/package.json index f98b05a..20d2621 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "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": { From f5ba6e6494a69163bcdf9e94ec15a4978fcdb9b4 Mon Sep 17 00:00:00 2001 From: Kevin Bridges Date: Sat, 8 Sep 2018 14:20:10 -0500 Subject: [PATCH 3/5] plugin is now configurable --- README.md | 78 ++++++++++++++++++++++++++++++++++---------------- book/plugin.js | 39 ++++++++++++++++++------- package.json | 16 +++++++++++ 3 files changed, 97 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 87032ed..d71ae8f 100644 --- a/README.md +++ b/README.md @@ -50,38 +50,66 @@ 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" - ] - } - ``` - -- For https://legacy.gitbook.com/ usage, plugins are automatically installed. +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 + ``` -- For local gitbook usage run `gitbook install` to install and prepare - all plugins for your books: - ```shell - gitbook install - ``` +## Configuration -- For technical users _(ex: open source documentation)_, install the - plugin to your **devDependencies** as follows: +You may optionally supply the following configuration to this plugin: - ```shell - npm install --save-dev gitbook-plugin-folding-menu - ``` +
    +**book.json** +```js +{ + ... + "pluginsConfig": { + "folding-menu": { + "animationDuration": 500, + "sticky": true, + } + } + ... +} +``` -## Configuration +
-TODO: ?? document configuration +- **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 @@ -108,7 +136,7 @@ Release | What | *When* **NOTE**: This release is a **non-breaking change** _(i.e. no API was affected)_. -1. The **folding-menu** plugin is now configurable ... see: [Configuration]. +- This plugin is now configurable _(see: [Configuration])_. diff --git a/book/plugin.js b/book/plugin.js index 16b6bf4..dccb5a2 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,10 +67,12 @@ 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) { - return; + if (config.sticky && // when configured to be sticky -AND- + $activeTopSection.length === 0) { // the current active section has NO sub-content + return; + } } // sync our left-nav to display ONLY the active top section @@ -136,8 +155,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 +162,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 +172,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 20d2621..8675eca 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,22 @@ "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" From 6b97a7fd1e8544d1ffe1cdeb52002b0934011bfa Mon Sep 17 00:00:00 2001 From: Kevin Bridges Date: Sat, 8 Sep 2018 14:48:27 -0500 Subject: [PATCH 4/5] corrected json in code snippet --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d71ae8f..0d37c5b 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ You may optionally supply the following configuration to this plugin: "pluginsConfig": { "folding-menu": { "animationDuration": 500, - "sticky": true, + "sticky": true } } ... From d74b06d327664508a9c135f11c678f54565842fd Mon Sep 17 00:00:00 2001 From: Kevin Bridges Date: Sat, 8 Sep 2018 14:48:51 -0500 Subject: [PATCH 5/5] syntax correction --- book/plugin.js | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/plugin.js b/book/plugin.js index dccb5a2..69c0113 100644 --- a/book/plugin.js +++ b/book/plugin.js @@ -71,8 +71,7 @@ require(["gitbook", "jQuery"], function(gitbook, $) { // ... by simply no-oping if (config.sticky && // when configured to be sticky -AND- $activeTopSection.length === 0) { // the current active section has NO sub-content - return; - } + return; } // sync our left-nav to display ONLY the active top section