JSDoc – Customize output documentation files

By | October 28, 2016

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
  • At line # 142, add the following code which will generate the table listing the method and the description
<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>

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;
Vishal Monpara is a full stack Solution Developer/Architect with 12 years of experience primarily using Microsoft stack. He is currently working in Retail industry and moving 1’s and 0’s from geographically dispersed hard disks to geographically dispersed user’s mind leveraging geographically dispersed team members.

One thought on “JSDoc – Customize output documentation files

  1. AnnieEm

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

Leave a Reply

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