Default "Home" text and content for JSDoc

Question

After running a basic JSDoc compile/render from Node.js:

jsdoc file1.js file2.js

I get a well-formatted document using the default template inside a directory "out". Almost all is as expected!

But when opening the document, it always says "Home" on the index.html page, has no content on that initial page, and has "Home" in the sidebar navigation.

How and where do I notate the name of the project so that it replaces "Home"? I would also like to see a project description, as well as author and copyright information.

It seems like the most basic of things to do in a JSDoc, but I can't find the information! I have tried the following, based on some random article I found on the internet:

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

But I get no love.

[edited to add:]

Discovered the @file / @fileOverview / @overview (all synonyms) directive, which is somewhat helpful as I can now describe and set copyright/author information for each file:

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

That leaves 2 "problems" to solve still:

1. An overview description; I think @file takes care of most of my needs, but since it's per-file, I would still like an "introduction" type paragraph or overview paragraph that appears before the descriptions of included files.

2. Replacing that "Home" text with custom text

Flutterboard

Just commenting to add that I have not found myself an abundant amount of time to test out the solutions proposed in the answers other than the accepted one. I encourage other people who stumble across this question to explore those other answers as well. Once I do so myself, I may update the current accepted answer. – Flutterboard

Answer 1

Generate Home page

Create markdown file README.md

Generating jsdoc:

$ jsdoc path/to/js path/to/readme/README.md

To read more about this visit official documentation

Change 'Home' text

I don't think this is a proper way to do it but this works.

If you have jsdoc installed in your project find template file in your working directory, mine was:

./node_modules/jsdoc/templates/default/publish.js

Then search for 'Home' with search command and replace with your text, next step is to specify template when generating jsdoc:

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/

Fefeal

Very useful! Don't suppose you've come across a solution to the "Home" text thing? – Flutterboard

Also you can edit conf.json where you would have to specify template only once – Fefeal

I was trying to avoid conf.json but I think I will be switching to it. Some of the options are more easily maintained with the conf file. I was also hoping to avoid tampering with the default template, but if that's all I can do then I guess I have little choice. Thanks for your help! – Flutterboard

I've submitted a small, two-line PR to make this property configurable here: github.com/jsdoc3/jsdoc/pull/1570 – Barometer

@Fefeal Is it possible to include two md files? – Gaming

Thanks, helpful :) – Thibodeau

Answer 2

I can't comment so I'll add a note here to clarify how to do all of the things in the original question without altering the default template, based on the directions in a file found in the "\npm\node_modules\jsdoc\templates" folder, which explains how to create your own templates. The steps to change the "Home" headings in the generated js documentation to project specific headings (e.g., "MyDescription") and include the overview blurb at the top of main page are outlined below.

Steps

1. First, to get the general overview onto the top of the main page of the js documentation, you would make the simple text file named README.md written in Markdown as per the answer and link above. The entire text appears at the top of the page if the path to that file is included in the command line as shown above or a reference is added in a file named conf.json, in which case you can use jsdoc -c pathTo\conf.json for the command line (see example in item 4 below). (As the link explains, you could make a file with any name or extension as long as it is in Markdown and you tell jsdoc where to find it).
2. Copy the folder and contents for the default template (\npm\node_modules\jsdoc\templates\default) to a new directory, renaming the new folder to something like myTemplate.
3. Using the advice from above for Change 'Home' text, search the file named publish.js inside the new myTemplate folder and replace "Home" with "MyDescription". Two points to note here: the file name has to remain publish.js, and "Home" appeared in two places in my original "publish.js", in the line

   var nav = '<h2><a href="index.html">Home</a></h2>';

   and the line starting generate('Home',....

4. Tell the jsdoc generator where to find your custom template (myTemplate folder) and your overview file ("README.md"). You can add -t pathTo\myTemplate to the command line, or you can use a very short command line, jsdoc -c pathTo\conf.json if you create a file named conf.json in a text editor, something like the file below, which specifies the source, destination, etc. for the documentation. That file puts the overview into the main page by telling the doc generator to use README.md in the "source" section, and changes the headings from "Home" to the new heading, "MyDescription", using the new myTemplate folder in the "opts" section.

   {
       "tags": {
           "allowUnknownTags": true,
           "dictionaries": ["jsdoc","closure"]
       },
       "opts": {
           "template": "pathTo/myTemplate",
           "destination": "pathTo/myJScriptDocs",
           "recurse": true
       },
       "source": {
           "includePattern": ".+\\.js(doc)?$",
           "excludePattern": "(^|\\/|\\\\)_",
           "include": ["pathTo/myJSSources", "pathTo/README.md"]
       },
       "plugins": [],
       "templates": {
           "cleverLinks": false,
           "monospaceLinks": false
       }
   }
   

Hyperaemia

Interresting answer. But, having a README.md at the project root, i've tryed, for pathTo/README.md : README.md, ./README.mf... I always get a File not found error. A shame that the JSDoc doc is not very verbose... – Cooncan

By adding the path to the README.md solved for me, maybe you should have the readme file in your project root folder? And then the include should only have the ["..." , "README.md"] as it is in the same root. – Ivie

Answer 3

You can also add an @file (or @fileOverview) to one or more of your source files.

All of the files' overview sections will be included on the JSDoc home page. If you also feed your README to JSDoc, the file overviews will be placed after the Readme content.

Example:

/**
 * @file index.js is the root file for the example.
 * It kicks things off.
 * @author Your name goes here
 * @see <a href="https://developers.docusign.com">DocuSign Developer Center</a>
 */

Harvell

Answer 4

'Home' is harcoded (passed as title when generating the index) in the default template so there is no variable or config that you could set to modify this title.

If multiple people are generating/editing the docs, editing the node_modules is an obvious no-go.

It's enough to create a layout.tmpl (or a full custom template, if you're using one), point JSDoc to it (CLI option or config file) and replace <?js= title ?> with <?js= title==='Home' ? 'Your Title' : title ?>.

Superintendent

Answer 5

I had a similar but different problem with the Home Page. The small in-house JavaScript library that I wanted to generate JSDOC pages for was just a collection of global functions, and I didn't want to display the home page at all. I only want to display the global.html page.

Since we use NPM to install JSDOC, I didn't want to duplicate the entire module just to customize the global page. Instead, I copied just the layout page to a separate directory and specified that in my jsdoc.json config file:

"templates" : {
  "default": {
    "layoutFile": "config/layout.tmpl"
  }
}

and then I edited layout.tmpl to add a <style> tag, with a style rule that does not display the link to the home.html page:

nav > h2 {
  display: none;
}

Absentee