Notes on building docs with JsDoc custom partials

This is a quick brain dump I did while I was working on JsDoc today aiming to help someone (me) in the future. Let me know in the comments if you need clarifications over certain aspects or want me to expand further.

Partials are elements that are used to build and customize a template. A template is a collection of partials.

In jsdoc, these partials can be used to customize components of the general documentation template to generate your own output. The documentation for jsdoc for creating custom partials goes over this in detail but it missed the context. So I thought I demonstrate some with an example.

Understanding jsdoc’s default template

Jsdoc’s templating engine is using HandlebarsJS partials and the default template is called document with markdown (DMD). Your project might be using its own template, but like I mentioned above. A template is a collection of partials. Hence, no matter if you are using jsdoc’s template natively or using it in your custom template. Things will work out just fine.

The documentation does great in describing the template structure, and how to override a partial already present in that template. Let’s have some fun with that, shall we?

Overriding partials with your own content

Hopefully, the documentation provided you with a clear understanding of Jsdoc’s template structure. We will be editing the main.hs partial and see what we can do there. One thing to note is handlebar partials are super name sensitive hence when overriding a partial, make sure you get the name right. Check out this example project that I created for this blog post.

Step 1: Copy the main.hs partial into the root of your project with the same name and make some changes.

{{>main-index~}}
I am a custom piece of documentation, rejoice!
{{>all-docs~}}

Step 2: Write some code

/**
 * A module for adding two values.
 * @module add-two-values
 */

/**
 * Add two values.
 * @alias module:add-two-values
 */
 function add (a, b) {
  return a + b
}

module.exports = add

Step3: Generate the documentation using the command:

jsdoc2md --partial main.hbs --files sample.js > DOCUMENTATION.md

Step 4: Here’s the output below in markdown. Since we don’t have an index generated in the code. The partial we overwrote renders our custom text between {{>main-index~}} and {{>all-docs~}}

Creating new partials

Now, let’s say you intend to create a new partial and add that to your own template. Let’s see how you could do that.

Step 1: I created a new file called docs-template.hbs. You can name the file as you wish. As I mentioned before, templates are a collection of partials. I am using the part {{>main}} in my new template to render the remaining documentation below the template text.

## Super important documentation 

Below you will find docs for the meaning of life: 

{{>main}}

Step 2: Test it out,

jsdoc2md --template docs-template.hbs --files sample.js > partial-docs.md

Step 3: Let’s create a new partial. We will call the file new-partial-over-here.hbs and refer it in the primary template like this.

## Super important documentation 

Below you will find docs for the meaning of life: 

{{>main}}
{{>new-partial-over-here}}

Step 4: Last step, add the partial flag to your previous command and render the documentation.

jsdoc2md --partial new-partial-over-here.hbs --template docs-template.hbs --files sample.js > partial-docs.md

Step 5: Here’s how the output looks in markdown format.

And, voila. You got it. This is how you can overwrite default partials for jsdoc and when you need to create new ones according to your template. All of this code is available in my example repository for you to experiment with and eventually copy. Hope this helped and always live in the mix.

Further reference: Check out this PR I made adding a partial to balena’s SDK documentation rendered using Jsdoc