Skip to content

dmh/modern-jsdoc-template

Repository files navigation

Modern JSDoc default template

Modern JSDoc default template with a Dark/Light theme style that closely resembles the Dark/Light theme found on GitHub

Run tests node-current JavaScript Style Guide JSDoc

screenshot

Table of contents

Why?

Dark/Light theme

This template enhances the simple and minimalistic JSDoc default template by incorporating a dark and light theme styling, similar to GitHub's dark dimmed and light theme. There are no other significant alterations.

Goal

Minimal changes to the default theme.

The JSDoc default theme has undergone minimal changes. The template only includes new styles and slight external script additions to the JSDoc default template. The main functionality and features remain unchanged. During the build process, most of the templates are copied from JSDoc without any modifications, ensuring alignment with the JSDoc default template in terms of features and functionality.

Features:

  • Dark/Light theme similar to GitHub light and dark dimmed themes
  • Highlight.js as a code syntax highlighter instead of prettify.js
  • Table of contents based on tocbot.js
  • initial.css as a base root CSS styling

Comparison Table

JSDoc default template Modern JSDoc template
Publish Script publish.js publish.js (no changes, same as in JSDoc default template)
Code syntax highlighter script prettify.js(self-hosted) highlight.js (CDN)
Code line numbers script linenumber.js (self-hosted) highlightjs-line-numbers.js (CDN)
General CSS styling JSDoc default Dark/Light theme (similar to GitHub)
Code syntax highlighter styles JSDoc prettify.js theme Dark/Light theme (similar to GitHub)
Layout Template JSDoc default layout JSDoc default layout with some modifications to add scripts and styles
All others templates JSDoc default Same as in JSDoc default, no changes!
Fonts OpenSans (external) system fonts
Table of contents no yes

Quick start

  1. Install jsdoc
npm install --save-dev jsdoc
  1. Install modern-jsdoc-template
npm install --save-dev modern-jsdoc-template
  1. Specify a source and template in jsdoc.json
{
  "plugins": ["plugins/markdown"],
  "source": {
    "include": ["source???/"]
  },
  "templates": {
    "cleverLinks": true,
    "default": {
      "includeDate": false
    }
  },
  "opts": {
    "template": "node_modules/modern-jsdoc-template/default",
    "readme": "./README.md",
    "destination": "./docs/",
    "recurse": true,
    "verbose": true
  },
  "markdown": {
    "idInHeadings": true
  }
}
  1. Generate documentation
npx jsdoc -c jsdoc.json

Contributing

  1. Clone/fork the repository and run npm install to install dependencies.
  2. Run npm start to start the development server with watcher.
  3. Add your changes to src/* files and test the result in browser on http://localhost:8082
  4. Run npm test to run tests.
  5. Commit your changes and create a pull request.

Thanks