JSDoc – Customize output documentation files

Category: JavascriptTags: ,

I am using JSDoc 3.4.2 for my JavaScript library documentation. I wanted to make the change to the output files so here are the tricks I used to make following changes. In order to make the change, I have copied all the files from the default template available at “C:\Users\USERNAME\AppData\Roaming\npm\node_modules\jsdoc\templates\default” (JSDoc over Node.js location) to “c:\temp\mytemplate” (=TEMPLATE_ROOT) and used “-t” argument to provide path to the template that I customized

jsdoc --debug -c "C:\temp\jsdocconf.json" -t "c:\temp\jsdoctemplate" -d "C:\temp\doc" "C:\temp\pramukhime.js"

Remove the JSDoc credit from the bottom of the page

Open the file TEMPLATE_ROOT/tmpl/layout.tmpl

Remove the whole footer tag from the bottom

Remove the source code beautification code (i.e. prettify)

Open the file TEMPLATE_ROOT/tmpl/layout.tmpl

Remove the needed “script” and “link” tags from the “head” section and at the very bottom

Remove the “Home” (=index.html) link from each page

Open the file TEMPLATE_ROOT/publish.js

In the function “buildNav” at line # 346, set the variable “nav” value to zero length string

var nav = ”;

Stop generating index.html file

Open the file TEMPLATE_ROOT/publish.js

At line # 582, you will find the following code.

generate('Home',
    packages.concat(
        [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}]
    ).concat(files),
indexUrl);

Comment out the code and it will not generate “index.html” file

Add the list of Methods in a table before method details

Open the file TEMPLATE_ROOT/tmpl/container.tmpl

<table class="params">
    <thead>
        <tr>
             <th>Name</th>
             <th class="last">Description</th>
        </tr>
    </thead>
    <tbody>
        <?js methods.forEach(function(m) { ?>
        <tr>
            <td><a href="#<?js= m.name ?>"><?js= m.name ?></a></td>
            <td><?js= m.description ?></td>
        </tr>
        <?js }); ?>
    </tbody>
</table>

At line # 142, add the following code which will generate the table listing the method and the description

Add css within the html page without dependency on .css file

Open the file TEMPLATE_ROOT/tmpl/layout.tmpl

In the “head” tag, add the needed styles

Remove unnecessary files/folders from TEMPLATE_ROOT/static/

This way, you will have only html as output

Generate lower cased output file

Please note that this requires change in the global JSDoc files and it will affect all the documentations generated from the installed JSDoc

Open the file JSDOC_ROOT/lib/jsdoc/util/templateHelper.js

Locate the function getUniqueFilename at line 118

Change the return value of this function to lower case at line 139

If you have existing files, delete those files and regenerate the documentation files again. If you don’t delete the existing files and you have Windows OS, this change will still show you the file names with mixed case

return makeUniqueFilename(basename, str).toLowerCase() + exports.fileExtension;

Share

5 comments

Your email address will not be published. Required fields are marked *

  1. Ankit Lalan says:

    Hey Vishal,
    That was a nice tweak. Thanks for sharing it.
    Though I was able to customize template as mentioned above for – “Add the list of Methods in a table before method details”, I have trouble using the “href”. The Id of the method includes “~” example: .
    but with
    <a href="#”>
    it is unable to find that particular id. Any help for functions which are static or inner?

    1. Hello Ankit,

      You may want to identify the object properties which represents static or inner methods and use those property names instead of what is given in my code.

      Regards,
      Vishal Monpara

  2. Sadaf says:

    Thank you Sir! it really helped a lot.

  3. AnnieEm says:

    All the things I wanted to do! You saved me a lot of time. Thanks!