JSDoc: How do you include a custom css file template in your generated docs?

The JSDoc docs say

Copying a directory of images to the output directory. To copy all of the static files in ./myproject/static to the output directory:
    "default": {
      "staticFiles": {
        "include": [
            "./myproject/static"
        ]
      }
    }
JavaScript
x
8
1
    "default": {
2
      "staticFiles": {
3
        "include": [
4
            "./myproject/static"
5
        ]
6
      }
7
    }
8
If your static files directory contains the file ./myproject/static/img/screen.png, you can display the image in your docs by using the HTML tag <img src="img/screen.png">.

And so I have this in my jsdoc.config.json

    "templates": {
        "default": {
            "staticFiles": {
                "include": [
                    "doc/_static/css/index.css"
                ]
            }
        }
    }

JavaScript
 
    "templates": {
        "default": {
            "staticFiles": {
                "include": [
                    "doc/_static/css/index.css"
                ]
            }
        }
    }
​

My css file gets added to the folder with my generated docs,

but I would really like all my generated docs to include that css file, and not have to manually put a <style src="index.css" /> tag manually into my auto-generated docs

It’s not there in the head of my auto generated docs, as you can see from the picture below

I would like the head to be something like

<head>
    <meta charset="utf-8">
    <title>JSDoc: Home</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="index.css">
</head>

JavaScript
 
<head>
    <meta charset="utf-8">
    <title>JSDoc: Home</title>
​
    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="index.css">
</head>
​

Answer

I think you may need to provide a custom layout (HTML) file using templates.default.layoutFile configuration property.

"templates": {
    "default": {
        "layoutFile": "custom-layout.tmpl"
    }
}

JavaScript
 
"templates": {
    "default": {
        "layoutFile": "custom-layout.tmpl"
    }
}
​

The path to the file is relative to:

Relative paths are resolved against the current working directory; the path to the configuration file; and the JSDoc directory, in that order.

This is an example template file to use for templates.default.layoutfile

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title><?js= title ?></title>
    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <link type="text/css" rel="stylesheet" href="dark.css">
    <link type="text/css" rel="stylesheet" href="index.css">
</head>
<body>

    <nav class="sidebar">
        <header class="nav-header">
            <a href="index.html">
                <img class="nav-logo" src="images/logo.svg" src="image" onerror="this.onerror=null; this.src='images/logo.png'" alt="alt text" />
                <h1>Project Name</h1>
            </a>
        </header>

        <?js= this.nav ?>
    </nav>

    <div id="main">
        <h1 class="page-title"><?js= title ?></h1>

        <?js= content ?>
    </div>

    <br class="clear">

    <footer>
        Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc <?js= env.version.number ?></a>
    </footer>

</body>
</html>

JavaScript
 
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title><?js= title ?></title>
    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <link type="text/css" rel="stylesheet" href="dark.css">
    <link type="text/css" rel="stylesheet" href="index.css">
</head>
<body>
​
    <nav class="sidebar">
        <header class="nav-header">
            <a href="index.html">
                <img class="nav-logo" src="images/logo.svg" src="image" onerror="this.onerror=null; this.src='images/logo.png'" alt="alt text" />
                <h1>Project Name</h1>
            </a>
        </header>
​
        <?js= this.nav ?>
    </nav>
​
    <div id="main">
        <h1 class="page-title"><?js= title ?></h1>
​
        <?js= content ?>
    </div>
​
    <br class="clear">
​
    <footer>
        Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc <?js= env.version.number ?></a>
    </footer>
​
</body>
</html>
​

Advertisement

Answer