Gitbook Plugins

The Bandwidth doc site relies on a few custom plugins. Most of which are stored under github.com/dtolb. These were usually slightly tweaked from another plugin to meet our specific needs. There are, however, a few plugins that make little to no sense without context and are very specific to building the Bandwidth documentation.

Docs-theme

The biggest plugin by far in the Bandwidth documentation suite. The docs-theme contains all the common styling for each doc site. Any new gitbook can use this plugin to relatively theme the site to match Bandwidth's design patterns. Each site still contains some custom styling across components and classes, but it should be kept to a minimum. The bandwidth docs-theme was originally forked from gitbookio/theme-api. It has diverged a good bit, and now tracks itself without a pointer to the original source.

Since the docs-theme contains the global styling for each project, each project forces a version of the docs-theme within the book.json: "theme-bandwidth@1.9.3". This allows us to ensure that each site looks good with all the changes before bumping the version. It also allows us to push a big change to a specific doc site and maintain the old styles until vetted. Perhaps not the intended nor best way to manage changes, but only really falls flat when all sites need a simple version bump.

The docs-theme uses NPM's prepublish script to call a bash.sh file that uses uglify & lessc to minimize the CSS and javascript before packaging the contents to NPM. The bash file makes the assets folder which is referred to in the proper NPM package.

Some notes on docs-theme deployment and build scripts

NPM is deprecating some of the scripts use to deploy and build the docs theme. It should be fine for a while, but the deployment and build process of the docs-theme uses old NPM patterns to begin with (requiring some tools to installed globally) and should be self-contained.

custom-jquery-postprocessing

Probably the hacky-est plugin ever written for gitbook. Located at https://github.com/dtolb/gitbook-plugin-customJquery. This takes advantage of the finish hook in the gitbook build process to manipulate the final rendered HTML with, well, custom jquery. It was originally written as a way to intercept the POST, GET, PUT, etc... in the SUMMARY file to add a class like <code class="post">POST</code> so the CSS can style it better. (see the messages example).

The plugin looks for a file located specified in the customJquery.js portion of the pluginsConfig portion of the book.json.

"customJquery": {
  "js": "js/custom.js"
},

It is expected that the file specified will export a function accepting the jquery library $ as it's only parameter. The final line of the exported function should always be: return $.html(); which re-renders the page to HTML to be served.

It has since become the default place to throw small tweaks instead of writing out a new plugin. We use this plugin to hide/show some elements in different pages. The best way to approach this would be to look at some of the custom.js files:

• ap-docs
• dev.bw
• v2-messaging
• iris-docs

There are some common patterns across each file, but they are somewhat unique to each site.

Style HTTP Verbs

This finds the HTTP verbs within the 'summary' and wraps them with the class. In order for this to work properly: in the SUMMARY the link should be something like [POST /messages](methods/messages/post.md) with the POST having a space afterwards.

$('li.chapter').each(function (i, elem) {
  var li = $(elem);
  if (li.text().indexOf('GET') > 0) {
    var newTxt = li.children().first().html().replace("GET", "<code class=\"get\">GET </code>");
    li.children().first().html(newTxt);
  }
  else if (li.text().indexOf('POST') > 0) {
    var newTxt = li.children().first().html().replace("POST", "<code class=\"post\">POST</code>");
    li.children().first().html(newTxt);
  }
  else if (li.text().indexOf('DELETE') > 0) {
    var newTxt = li.children().first().html().replace("DELETE", "<code class=\"delete\">DEL </code>");
    li.children().first().html(newTxt);
  }
  else if (li.text().indexOf('PUT') > 0) {
    var newTxt = li.children().first().html().replace("PUT", "<code class=\"put\">PUT </code>");
    li.children().first().html(newTxt);
  }
  else if (li.text().indexOf('PATCH') > 0) {
    var newTxt = li.children().first().html().replace("PATCH", "<code class=\"patch\">PAT </code>");
    li.children().first().html(newTxt);
  }
});

Adding #top to specific pages

As a workaround for some extendedMethod pages (ones that have alternate between double column and triple column layouts), the #top is added to the URL to make the site pre-scroll just a tiny bit to display the page better. It's also very useful when scrolling and clicking within the page to enqueue the #top into the back->forward buffer of the browser.

var helperPages = [
  'uisetup.html',
  'apisetup.html',
  'orderingSummary.html',
  'disconnectSummary.html',
  'restAPI.html',
  'manageLocations.html',
  'portingPhoneNumbers.html',
  'managingLineFeatures.html',
  'reporting.html'
];



$('li.chapter a').each(function(i, elem) {
  var a = $(elem);
  var link = a.attr("href");
  helperPages.forEach(page => {
    if(link.endsWith(page)) {
      a.attr("href", link+'#top');
    }
  });
});

Replacing the title to remove gitbook

By default, gitbook places its own name in the title of the page. We wanted to remove that.

var title = $('title').text();


if(title.indexOf(' · GitBook')  > 0) {
  var newTitle = title.replace(' · GitBook', '');
  $('title').text(newTitle);
}

Forcing links to open in same tab

Since the entire suite of the Bandwidth documentation is managed in multiple different sites (really exploiting the way github pages operates), some links that should open in the same tab, are opened in a new tab by default. In order to prevent the target attribute from working, we remove that attribute from links that shouldn't open in new tabs.

$('ul.summary a:contains(Full API Reference),ul.summary a:contains(BXML Reference),ul.summary a:contains(Messaging v2 Reference),ul.summary a:contains(Phone Numbers Reference) ').removeAttr('target');

Other Plugins

There are other plugins that shape the way the documentation looks and behaves:

Plugin	General description
bandwidth-highlight	For some reason, gitbook defaulted to highlighting json the same as javascript with highlight.js. This undoes that and adds our chosen color highlighting scheme
custom-favicon	Replaces the gitbook favicon with Bandwidth's. This plugin was forked and modified to (what I think) is a better version at bring-yer-favicon. However, it has not been a priority to update this plugin
usabilla	Adds the usabilla floater to the docs pages
crazy-egg	Adds crazyegg javascript to the docs
bandwidth-fonts	When removing the default font settings (-fontsettings) in the book.json and adding bandwidth-fonts the docs theme will use the appropriate fonts
include-html	Replaces the !INCLUDE "file.html" phrase with the indicated HTML file. Useful for custom HTML pages from the design or marketing team
custom-footer	Adds the footer with links to each page. Originally requested by the marketing team for better SEO back to bandwidth(dot)com proper
bandwidth-toggle-chapters	Toggles the nested bullet points in the SUMMARY.md file to better represent the desired information architecture (IA)
talkus	Add talkus chat button to gitbook web pages. Only used for the Phone Number API docs right now. Be careful adding this plugin to other pages, in the past it has been a haven for pointless repetitive questions.
save-url-to-file	Saves whatever is at the url specified to the dest specified for each. Downloads the file and then moves it to that location in the generated _book. This is mainly used to pull the RAML and the Errors pages that generated from the source code.