Login/Register
JSDoc: How do you include a custom css file template in your generated docs?
Asked Answered
Solved javascriptcssjsdocjsdoc3
C

1

3

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"
        ]
      }
    }

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"
                ]
            }
        }
    }

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>
Clingstone answered 24/3, 2022 at 5:45 Comment(0)
P
4

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

"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>
Pragmatic answered 26/3, 2022 at 10:31 Comment(6)
Where does templates.default.layoutFile go? – Clingstone
Into the json config, updating – Pragmatic
Could you provide an example config file please? – Clingstone
Whats inside custom-layout.tmpl – Clingstone
I found an example template file but am still having troubles, I don't think it's being read. Could you please provide a more in depth answer that contains everything needed to run, the jsdoc documentation is not very descriptive. I'm getting SyntaxError: Unexpected token '<' but have no idea which < it's talking about – Clingstone
I found out the syntax error, I was missing a ? – Clingstone

© 2022 - 2024 — McMap. All rights reserved.