Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
README.md
staticFiles.js

README.md

staticFiles

staticFiles is a plugin for including static assets in documentation generated by JSDoc. Based on user specified settings, it can copy files and directories with inclusion and exclusion patterns, with an option for recursively copying directories.

How to use

The first step to using staticFiles is to create some files which need to be packaged with the resulting documentation. These files can be of any type, be it images, stylesheets or scripts. Next step is to create a configuration file for JSDoc, if one does not exist already, and add configuration for this plugin.

Configuring the plugin

Options can be passed to the plugin using JSDoc's configuration file. Various parameters can be passed on to a staticFiles object in the JSDoc's configuration file.

Let us assume that the user has written all tutorials in the tutorials folder. Those tutorials need images which are present in the tutorials/images folder. They need to be copied to images folder in the generated documentation, so that the relative links to images in the tutorials work in the produced documentation. The user needs to ensure that only .png and .jpg files are copied from the source folder, but needs to exclude tutorials/images/2.jpg from getting copied. The copy needs to be done recursively, but only till 2 levels of subfolders. The configuration for this use case will look like this:

{
  "staticFiles": {
    "include": ["images:tutorials/images/",],
    "exclude": ["tutorials/images/2.jpg"],
    "includePattern": ".+\\.(png|jpg)$",
    "excludePattern": "(^|\\/|\\\\)_",
    "recursive": true,
    "recursiveLevel": 2,
  }
}

Notice that the staticFiles configuration is not part of the templates configuration. It has to be outside the templates configuration, as part of the root.

Installation

  • Copy the staticFiles directory to your JSDoc's plugins directory. So the plugin file will be at <jsdoc>/plugins/staticFiles/staticFiles.js.

  • Edit your JSDoc configuration file and add plugins/staticFiles/staticFiles to the plugins array:

    "plugins" : ["...", "plugins/jsdoc-plugins/staticFiles/staticFiles"]
    
  • Create plugin specific configuration in the same configuration file. See Options details for configuration options.

  • Put your images in tutorials/images relative to the folder from which you execute jsdoc.

  • Ready to go!

Options details

Parameter Description
include It is the primary configuration option for specifying the folders to copy. It is an array where the source paths are specified as strings. A special format can be used to specify different source and destination paths, where the path is written as "destination:source", separated by a colon. e.g. if the source is tutorials/images, but the output destination needs to be images, then the string has to be written as "images:tutorials/images". Since this option is a array, multiple separate include paths can be specified, delimited by a comma.
exclude An array of files in the included source folders that should be excluded. For example, ["tutorials/images/2.jpg"] will exclude only that file.
includePattern Within the included folders, only files that match this regex pattern will be included.
excludePattern Within the included folders, the files matching this pattern will be always excluded. This will take precedence over includePattern.
recursive If true, the source folders will be recursively copied. Defaults to false.
recurseLevel If recursive is true, this provides the depth of levels that the recursion should go. This is 3 by default.
Something went wrong with that request. Please try again.