clean-jsdoc-theme

clean-jsdoc-theme

A beautifully crafted theme/template for JSDoc 3. This theme/template looks and feels like a premium theme/template. This is a fully mobile responsive theme and also fully customizable theme (for more look below in feature section).

I give extra care on every part of this theme/template, like instead of using a simple search mechanism I have used one of the most advance search technology Fuse.js.

Feel free to raise issues,

Live demo (dark): https://ankdev.me/clean-jsdoc-theme/dark/index.html
Live demo (light): https://ankdev.me/clean-jsdoc-theme/light/index.html

Demo screen

Install

Note you must have npm installed on your machine.

On your command line type

npm install clean-jsdoc-theme

Usage

Clone repository to your designated jsdoc template directory, then

jsdoc entry-file.js -t path/to/clean-jsdoc-theme

Node.js Dependency

In your projects package.json file add a generate script

"script": {
  "generate-docs": "node_modules/.bin/jsdoc --configure .jsdoc.json --verbose"
}

In your jsdoc.json file, add a template option.

"opts": {
  "template": "node_modules/clean-jsdoc-theme"
}

Example JSDoc Config

{
    "source": {
        "include": ["lib", "package.json", "README.md"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },

    "plugins": ["plugins/markdown"],

    "opts": {
        "encoding": "utf8",
        "readme": "./README.md",
        "destination": "docs/",
        "recurse": true,
        "verbose": true,
        "template": "./node_modules/clean-jsdoc-theme"
    }
}

Features

I believe in giving freedom to the developer, that's why I have given many options to the developer to customize this theme according to their needs. You can pass an object called theme_opts under opts for more options like:

"opts":{
  /*
    Default options
  */
  "theme_opts":{
    // Set theme. Default is light
    "theme": "dark",
    /*
      Instead of only string you can pass html element like
      <img src="src to your img relative to the output path" class="my-custom-class"/>
      Path must be relative to the output file (relative to generated html files.) you
      can use the absolute path.
      Note: If you use html the default overwrite. Also for custom class you have to create
      a class using create_style.This is shown below.
    */
    "title": "clean-jsdoc-theme",

   "filter": false, /*  The default value is true. This will turn the color of image white.
      If you did not want any
      filter set it to false.
   */

  // Adding additional menu.
  "menu": [
    {
      "title": "Website", //You have to give title otherwise you get error.
      "link": "https://ankdev.me/clean-jsdoc-theme/index.html", // You have to give link otherwise you get error.
      // Below properties are optional.
      "target": "_blank",
      "class": "some-class",
      "id": "some-id"
    },
    {
      "title": "Github",
      "link": "https://github.com/ankitskvmdam/clean-jsdoc-theme/",
      "target": "_blank",
      "class": "some-class",
      "id": "some-id"
    }
  ],

  // You can pass meta options also
  "meta": [
      {
        "name": "author",
        "content": "Ankit Kumar"
      },
      {
        "name": "description",
        "content": "Best Clean and minimal JSDoc 3 Template/Theme"
      }
    ],

  "search": false, //This option is for either showing or hiding the search. By default it is true.

  // You can create custom style which will overwrite the exisiting class property.
  "create_style": "nav{background: yellow}", // This will change the background color of sidebar.
  // Use this option to add third party css library
  // Note: You have to pass an array of object, and object keys are actually the attributes which you want
  // in you link tag.
  "add_style_path": [
    {
      "href": "https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/css/bootstrap.min.css",
      "integrity": "sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1",
      "crossorigin": "anonymous"
    }
  ],

  // You can add custom script to html
  "add_scripts": "function foo(){console.log('foo')}",

  // Use this option to add third party js library
  // Note: You have to pass an array of object, and object keys are actually the attributes which you want
  // in you script tag.
  "add_script_path": [
    {
      "src": "https://code.jquery.com/jquery-3.5.1.js",
      "integrity": "sha256-QWo7LDvxbWT2tbbQ97B53yJnYU3WhH/C8ycbRAkjPDc=",
      "crossorigin": "anonymous"
    }
  ],

  "footer": "This is footer",   // Here again you can pass html element

  // Path should be relative to jsdoc configuration file.
  // Path to static dir which you want to copy to output dir
  "static_dir": ["./static"],

  // Include css files
  // Note: You are not required to manually copy file to output dir
  "include_css_files": ["./static/index.css", "./src/docs/index.css"],

  // Include js files
  // Note: You are not required to manually copy file to output dir
  "include_js_files": ["./static/main.js", "./third-party/test/index.js"],

  // Include overlay scrollbar
  "overlay_scrollbar": {
      "options": {
          // ...overlay options
          // If you want default then pass empty object
      }
  }

}

In version 3.0.0

New

1. Add an option to include css files.
2. Add an option to add js.
3. Add an option to include static folder.
4. OverlayScrollbar are now supported by default. If you don't want to use it pass an option to disable it.

Breaking changes

1. add_script_path previously you have to pass an string of array but now you have to pass an object where keys are the attributes of the script tag
2. add_style_path previously you have to pass an string of array but now you have to pass an object where keys are the attributes of the link tag
3. meta previously you have to pass an string of array but now you have to pass an object where keys are the attributes of the meta tag

In version 2.2.15

New

1. Scrollable code area

In version 2.2.14

Bug Fix

1. Malformed HTML when parsing 'default' JSDoc tags [issue: #48]

In version 2.2.13

New

1. Make the # before members and methods a clickable anchor. [pull request: #44] [Thanks to GMartigny]

Other

1. Change jsdoc into a peerDependency [pull request: #45][Thanks to GMartigny]

In version 2.2.12

New

1. Add dark theme.

Bug fix

1. Fix typescript-eslint camelCase rule issue [issue: #37]
2. Fix ordered list style [issue: #40]
3. Fix code overflow issue.

Developing

Before starting please go through our contributing guide.

git clone https://github.com/ankitskvmdam/clean-jsdoc-theme.git
cd clean-jsdoc-theme
npm install
npm install jsdoc --no-save
npm run test

npm run test will generate files in output folder.

Contact

If you like our work, then give me a star. This will act as a driving force to add new feature more frequently.
Mail me at: [e-mail]

License

Licensed under the MIT license.

Changelog

In version 3.0.0

New

1. Add an option to include css files.
2. Add an option to add js.
3. Add an option to include static folder.
4. OverlayScrollbar are now supported by default. If you don't want to use it pass an option to disable it.

Breaking changes

1. add_script_path previously you have to pass an array of string, but now you have to pass an array of object where keys are the attributes of the script tag
2. add_style_path previously you have to pass an array of string, but now you have to pass an array of object where keys are the attributes of the link tag
3. meta previously you have to pass an array of string, but now you have to pass an array of object where keys are the attributes of the meta tag