Navigation Menu

The responsive navigation menu that gets injected into the chosen jsdoc template can be modified to add a personalized look-and-feel using the provided opts.jsdocp.menu configuration options. Everything from the CSS class of the menu, an optional logo to each of the icons displayed can be changed.

Navigation Menu Positioning

There are four different media query-driven configuration options available that allows for custom positioning of the navigation menu. They include small (opts.jsdocp.menu.SM), medium (opts.jsdocp.menu.MD) and large (opts.jsdocp.menu.SM). Each media region (small, medium and large) can be calibrated using the matchMedia to determine when the menu positioning will be applied. Consider the following:

  "SM": {
    "position": "bottom",
    "autoHide": true,
    "matchMedia": "(max-width: 480px)"
  },
  "MD": {
    "position": "left",
    "autoHide": true,
    "matchMedia": "(min-width: 481px) and (max-width: 839px)"
  },
  "LG": {
    "position": "top",
    "autoHide": false,
    "matchMedia": "(min-width: 840px)"
  }

When a clients browser matches (max-width: 480px), SM is applied causing the navigation menu to be displayed at the bottom of the screen and will be hidden when the page is scrolled down and visible when scrolled up. Similarly, MD or LG will be applied when they match the client's browser size (in that order of precedence).

The Logo

By default, no logo is used. Only the package.name is displayed in the navigation menu. However, if a logo is desired there are a few options available. When the opts.jsdocp.menu.logo.src is set the logo will be rendered as a simple img. This option is adequate when styling is not needed, but if the logo is in svg format and it needs to be styled it falls short. To accommodate svg styling, a separate opts.jsdocp.menu.logo.inlineSvgPath can be defined that provides a path to an svg that will be loaded into the logo link as the raw svg content rather than an img. This permits the opts.jsdocp.menu.logo.className to style the logo for the svg elements (e.g. fill: red). For more information on available logo options, see the configuration options for publicize.

The npm Package Icon

By default, an npm icon/link is displayed that points to https://www.npmjs.com/package/<your_package_name> from the name defined in package.json. This option can be supressed by setting opts.jsdocp.menu.package to none and can be customized be setting the same option to a value that will be used on the image src for the icon. The default icon is rendered as an svg so that the icon can be styled/colorized via opts.jsdocp.menu.icons.className. For more information on available options for icons, see the configuration options for publicize.

The Changelog Icon

By default, a changelog icon/link is displayed that points to a parsed markdown file called CHANGELOG.html. This option can be supressed by setting opts.jsdocp.menu.changelog to none and can be customized be setting the same option to a value that will be used on the image src for the icon. The default icon is rendered as an svg so that the icon can be styled/colorized via opts.jsdocp.menu.icons.className. For more information on available options for icons, see the configuration options for publicize.

The Source Code Icon

By default, a source code icon/link is displayed that points to the homepage URL set in the package.json. This option can be supressed by setting opts.jsdocp.menu.sourceCode to none and can be customized be setting the same option to a value that will be used on the image src for the icon. The default icon is rendered as an svg so that the icon can be styled/colorized via opts.jsdocp.menu.icons.className. For more information on available options for icons, see the configuration options for publicize.

Version Selection

Documentation versions are managed via npm view <your_package_name> versions --json. Each published version to npm is captured when generating documentation and stored within a versions.json file under the jsdoc configuration directory set by opts.destination. The versions.json file contains a simple array of versions that will be loaded via the jsdocp JavaScript ran in the client's browser. During each deployment the versions.json gets overwritten in the root directory of the branch set by opts.jsdocp.deploy.branch. This allows both previously and the currently deployed docs to always reference the latest versions in the selection menu presented in the client's browser.

There are a few techniques that allow filtering of versions that are used on the client. The first involves setting the opts.jsdocp.versions.type option to either major or minor. When left unset no filtering is performed and all versions are available for client selection. In contrast, when major/minor is set, only versions that are published where the major/minor version changes are shown. For example, consider the following published versions:

• v1.0.0
• v1.0.1
• v1.0.2
• v1.1.0
• v1.0.1
• v1.2.0
• v2.0.0

When major is set the resulting versions selections shown would be:

• v1.0.0
• v2.0.0

Likewise, when minor is set the resulting versions selections shown would be:

• v1.0.0
• v1.1.0
• v1.2.0
• v2.0.0

Another technique is setting the opts.jsdocp.versions.from option to a version that will be used as a starting point. Using the same previous example version set, if from is set to v1.1.0 then the resulting versions selections shown would be:

• v1.1.0
• v1.0.1
• v1.2.0
• v2.0.0

NOTE: Keep in mind that the doc version being viewed will always be shown regardless of the filtering values that are set.

Static Resources

Although they are not technically part of the navigation menu, static resources like CSS, JavaScript and meta can be added using opts.jsdocp.links, opts.jsdocp.scripts and opts.jsdocp.meta, respectively. links and meta are added to the head of the page while scripts are added as the last elements within the body. The example configuration can be used as a guide as well as the documented options for publicize.

Globals >>