• page

Learn how to configure the documentjs.json file for your project.

In the root folder of your project, a documentjs.json file is used to configure your project's documentation. docConfig specifies the high-level structure and options allowed in the documentjs.json file. There are a lot of options. This guide walks you through the most common setups.

Configuring for multiple versions using github pages

This configuration assumes you:

  • Are using github pages to host your code's documentation.
  • Have installed as an npm dependency.

You will setup the code of your project to be documented and then setup an empty gh-pages branch to download and document that code.

  1. Create a documentjs.json file in your project's root folder.

    Specify a site that will find your project's documented files and generate them within a folder. The following will get all .md and .js files in the lib and docs folders and put them in an api folder next to your project's folder:

       "sites": {
         "api": {
           "glob": "{lib,docs}/**/*.{js,md}"

    Run documentjs and check that the output looks like:

     project> ./node_modules/.bin/documentjs
     project> cd ../api
     api> open index.html

    Make sure to commit and push your project's documentjs.json file.

  2. Create and clone a gh-pages branch.

    Create the branch:

     project> git checkout --orphan gh-pages

    Remove files not needed in the static site. Commit and push the branch:

     project> git rm -rf .
     project> touch documentjs.json
     project> git add documentjs.json
     project> git commit -m "first commit"
     project> git push origin gh-pages

    Clone the branch so you don't have to switch back and forth constantly:

     project> cd ..
     dev> git clone -b gh-pages git://
     dev> cd
  1. Install DocumentJS as an npm dependency> npm install documentjs --save-dev
  2. Create a gh-pages documentjs.json file.

    List the version number of your project and the branch where you added the first documentjs.json:

       "versions": {
         "1.0.0": "git://"

    By default, this will download the master into and then run its documentjs.json, creating For stable linking and SEO, you likely want your most recent production documentation in the same place. For example, you might always want the latest production API docs at The defaultVersion lets you specify a version that should get put in that location.

    Set defaultVersion to the version number of your project:

       "versions": {
         "1.0.0": "git://"
       "defaultVersion": "1.0.0"

    Checkout docConfig's documentation for how to change the location of the default version, and change the location of other versions, and add other behaviors.

  3. Generate the docs.

    Use documentjs to generate the docs:> ./node_modules/.bin/documentjs

    This will download all versions and generate their docs. This isn't ideal if you are trying to document a single version. You would have to commit and push to see changes. Instead, you can swap a specific version to be read from the filesystem like:> node_modules/.bin/documentjs 1.0.0@../documentjs

    This will use the local documentjs folder as the 1.0.0 version.

Configuring for a simple single version.

Coming soon.