Integrating GitBook with JSDoc to Document Your Open Source Project

Kevin Bridges
Apr 12, 2017 · 13 min read

At a Glance


Basics

{project-root}/package.json ... various npm scripts, INCLUDING docs generationbook.json   ... GitBook configurationsrc/        ... project source code (jsdoc2md scan root)
*.js ... embedded JSDoc comments defining my API
docs/ ... master source of my GitBook project documentation
toc.md . the summary TOC (seen in the left nav)
intro.md . the Guide Introduction
api.md . machine generated API docs (from jsdoc2md)
*.md . various Markdown files making up our docs
sectionN/ ... optional docs dirs (as required)
*.md
tooling/ ... various project build utils (scripts/config/etc.)
docs/ ... docs related
jsdoc.json . jsdoc2md configuration (for ES6 features)
*.hbs . jsdoc2md template overrides (handlebars)
_book/ ... machine generated docs (output of GitBook)
*.html
*.js
*.css

Docs Related Dev Dependencies

$ npm install --save-dev gitbook-cli
$ npm install --save-dev jsdoc-to-markdown
$ npm install --save-dev jsdoc-babel
$ npm install --save-dev babel-preset-es2015
tooling/
docs/
jsdoc.json
==========
{
"plugins": ["node_modules/jsdoc-babel"],
"babel": {
"presets": [ "es2015" ]
}
}

Basic GitBook Template

book.json (GitBook configuration)
=========
{
"gitbook": "3.2.2",
"root": "./docs",
"structure": {
"readme": "intro.md",
"summary": "toc.md"
}
}
docs/ toc.md (defines the left-nav)
======
# Table of content
* [Getting Started](start.md)
* [API Reference](api.md)
intro.md (docs introduction)
========
# astx-redux-util
The is our **introduction** to astx-redux-util. Here are some references to the [Getting Started](start.md)
and [API](api.md).
start.md (our getting started)
========
# Getting Started
This is the **Getting Started** section. Here are some references to the [Introduction](intro.md)
and [API](api.md).

Docs Related NPM Scripts

"docs:api": "jsdoc2md --configure tooling/docs/jsdoc.json --files src/**/*.js > docs/api.md"
"docs:prepare": "gitbook install"
"docs:build": "npm run docs:prepare && npm run docs:api && gitbook build"
"docs:serve": "npm run docs:prepare && npm run docs:api && gitbook serve"
"docs:clean": "rimraf _book"

Visualize Your Docs

$ npm run docs:prepare # run once (to initialize gitbook)
$ npm run docs:serve

Customizing jsdoc2md

Overriding jsdoc2md Output

$ cd node_modules/dmd$ find . | grep hbspartials/all-docs/all-docs.hbs
partials/all-docs/docs/body/access.hbs
... snip snip
partials/main.hbs ... THE STARTING POINT
... snip snip
partials/shared/value/link.hbs
partials/shared/value/linked-type-list.hbs
$ jsdoc2md --partial tooling/docs/<file>.hbs ...other-ops

Indexing the API from GitBook

* [API Reference](api.md)
* [conditionalReducer](api.md#conditionalReducer)
* [joinReducers](api.md#joinReducers)
* [reducerHash](api.md#reducerHash)

Improve API Headers

Make API Types Linkable

**Returns**: <code>[reducerFn](#reducerFn)</code> - snip snip
**Returns**: [`reducerFn`](#reducerFn) - snip snip

Minor API Adjustments


Customizing GitBook

Book Styling

/* slim left-nav width (was: 300px) */
.book-summary {
width: 250px;
}
.book.with-summary .book-body {
left: 250px;
}
/* condense left-nav spacing (was: 10px 15px) */
.book-summary ul.summary li a, .book-summary ul.summary li span {
padding: 5px 15px;
}
/* condense line-spacing */
.markdown-section {
line-height: 1.4; /* overall line-spacing (was: 1.7) */
}
.markdown-section pre {
line-height: 1.2; /* code-snippet line-spacing (was: 1.7) */
padding: .5em; /* also reduce padding around code block (was: .85em 1em) */
}

Toolbar Adjustments

plugins": [ "-sharing"],
"pluginsConfig": {
"sharing": {
"facebook": false,
"twitter": false,
"google": false,
"weibo": false,
"instapaper": false,
"vk": false,
"all": ["twitter", "facebook", "google"]
}
}
"plugins": ["toolbar"],
"pluginsConfig": {
"toolbar": {
"buttons": [
{
"label": "GitHub",
"icon": "fa fa-github",
"url": "https://github.com/KevinAst/astx-redux-util"
},
{
"label": "NPM",
"icon": "fa fa-bullseye",
"url": "https://www.npmjs.com/package/astx-redux-util"
}
]
}
}

Template Links

"variables": { 
"guide": {
"intro": "[Introduction](/intro.md)",
"start": "[Getting Started](/start.md)"
},
"api": {
"ref": "[API Reference](/api.md)",
"conditionalReducer": "[`conditionalReducer()`](/api.md#conditionalReducer)",
"joinReducers": "[`joinReducers()`](/api.md#joinReducers)",
"reducerHash": "[`reducerHash()`](/api.md#reducerHash)"
}
}
THIS: 
Here are some references to the {{book.guide.start}}
and {{book.api.reducerHash}}.
IS EQUIVALENT TO THIS:
Here are some references to the [Getting Started](/start.md)
and [`reducerHash()`](/api.md#reducerHash).

Project Name and Version

### astx-redux-util (1.0.0)

Disable Live Reloading

https://astx-redux-util.js.org:35729/livereload.js
plugins": [ "-livereload"],

Deployment

  "scripts": {
"docs:publish": "gh-pages --dist _book"
}

Final Result


Kevin Bridges

Written by

A “current” developer from a different era (70’s UMR alum) … from the greater St. Louis area (Metro East) … https://wiiBridges.com/

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade