clean-jsdoc-es5

Installation

⚠️ Installing from the GitHub Package Registry (currently) requires a personal access token (PAT) with the read:packages scope.

Be sure to authenticate with the registry via npm login, or by adding this line to a .npmrc file in your $HOME directory:

//npm.pkg.github.com/:_authToken=<YOUR_PERSONAL_ACCESS_TOKEN>

Quick start

GitHub package only

Add this line to a .npmrc file at the root of your project:

@clean-jsdoc:registry=https://npm.pkg.github.com

Install jsdoc:

npm i --no-save jsdoc

Install the template assets:

as a GitHub package:

npm i --save-dev @clean-jsdoc/clean-jsdoc-es5

. . . or, directly from the source tree:

npm i --save-dev clean-jsdoc/clean-jsdoc-es5

Now run:

npx jsdoc path/to/source/files -t node_modules/@clean-jsdoc/clean-jsdoc-es5 -r README.md

Workflow Integration

Configure jsdoc to use the template in your .jsdoc.json file:

If you installed the GitHub package:

  "opts": {
    "template": "node_modules/@clean-jsdoc/clean-jsdoc-es5"
  }

For example:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "idInHeadings": true
    },
    "source": {
        "include": ["lib", "README.md"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(node_modules/|docs)"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc", "closure"]
    },
    "opts": {
        "template": "node_modules/@clean-jsdoc/clean-jsdoc-es5",
        /* see below */
        "theme_opts": {},
        "encoding": "utf8",
        "readme": "./README.md",
        "destination": "docs/",
        "recurse": true
    }
}

Add a script to your package.json:

  "script": {
    /* ... */
    "gendocs": "node_modules/.bin/jsdoc -c .jsdoc.json --verbose"
  }

Build your documentation with: npm run gendocs

Options

All options must be defined under opts.theme_opts in your .jsdoc.json

Basic

name	purpose	type	default	options
`theme`	the overall style theme	string	`"light"`	`"light"`, `"dark"`, `"dynamic"` [1]
`search`	enable fuzzy search using Fuse.js	bool	`true`	`true`, `false`
`menuLocation`	sets the location of the optional external links menu relative to the doc navigation menu [2]	string	`"up"`	`"up"`, `"down"`
`langNames`	display language names in code blocks	bool	`true`	`true`, `false`
`moduleNames`	show the module's name in the page's top heading	bool	`false`	`true`, `false`
`sort`	sort members/methods/events by name	bool	`true`	`true`, `false`
`title`	the name of the home link to display on the nav bar	HTML string	`"README"`	any valid HTML markup, or just a plain string
`footer`	a footer to display in the page layout	HTML string	JSDoc version, date and theme info	any valid HTML markup
`inline_style`	inline CSS for the `<head>` of the page layout	CSS string	`null`	any valid CSS markup

[1] sets the theme according to the value of the prefers-color-scheme @media query; it falls back to "light"

[2] "up" == above navigation menu, "down" == below. Requires the menu option to be set

Advanced

`"project": {}`

Details of your project, e.g.

  "project": {
      "title": "clean-jsdoc",
      "version": "4.5.0",
      "repo": "https://github.com/clean-jsdoc/clean-jsdoc-es5"
  }

Required properties

name	type
`repo`	URL

Optional properties

name	purpose	type	default
`title`	the title of the project; it will appear in every page's `title` tag	string	`null`
`version`	the semantic version number	string	"1.0.0"

`"sections": [...]`

Documentation headings to include in the navigation menu, e.g.

  "sections": [
      "namespaces",
      "interfaces",
      "classes",
      "events",
      "tutorials"
  ]

Required properties

At least one of the following section labels (case insensitive):

    "classes"
    "externals"
    "events"
    "global"
    "interfaces"
    "mixins"
    "modules"
    "namespaces"
    "tutorials"

Unlisted labels will be ignored with a warning message. Leave this option undefined to include all sections detected by jsdoc.

`"menu": [{}, ...]`

A list of hyperlinks to add to the navigation bar, e.g.

  "menu": [
    {
      "title": "Website",
      "link": "https://rdipardo.bitbucket.io",
      "target": "_blank",
      "class": "some-class",
      "id": "some-id"
    }
  ]

Required properties

name	type
`title`	string
`link`	URL

Optional properties

name	type
`target`	HTML target attribute
`class`	CSS class selector
`id`	CSS id selector

`"meta": [{}, ...]`

A list of meta tag attributes to add to the head of each page, e.g.

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

Required properties

Any valid combinaton of HTML metadata attributes.

`"asset_paths": ["path/to/assets", ...]`

A list of local folders to search for static content files. Paths are relative to the current working directory, e.g.

  "asset_paths": [
      "img",
      "css/themes",
      "js/lib/jquery"
    ]

Required properties

None. If a path does not exist, or exists outside the working directory, it will be ignored with a warning message.

`"remote_assets": [{}, ...]`

A list of link tag attributes for asset resources, e.g.

  "remote_assets": [
    {
      "href": "https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/css/bootstrap.min.css",
      "integrity": "sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1",
      "crossorigin": "anonymous"
    },
    {
      "href": "img/favicon.ico",
      "rel": "shortcut icon",
      "type": "image/x-icon"
    }
  ]

Required properties

name	type
`href`	URL

Optional properties

name	purpose	type
`integrity`	A Subresource Integrity hash in base64 encoding	string
`crossorigin`	The CORS policy for the resource	string

Some assets will need additional link attributes to load properly.

As of version 2.0.0, this template can detect stylesheets and shortcut icons from the file extension in the href. Support for more media types may be added in future releases.

`"remote_scripts": [{}, ...]`

A list of script tag attributes for third-party JavaScript sources. e.g.

  "remote_scripts": [
    {
      "src": "https://code.jquery.com/jquery-3.5.1.js",
      "integrity": "sha256-QWo7LDvxbWT2tbbQ97B53yJnYU3WhH/C8ycbRAkjPDc=",
      "crossorigin": "anonymous"
    }
  ]

Required properties

name	type
`src`	URL

Optional properties

Mostly the same as remote_assets

`"overlay_scrollbar": { "options": {} }`

Includes the OverlayScrollbars plugin.

Required properties

None. Simply passing an empty object will activate this feature.

Optional properties

Any option supported by OverlayScrollbars.

`"codepen": { "options": {} }`

Puts an "Edit on CodePen" button next to code snippets in @example sections.

"codepen": {
  "options": {
    "js_external": "https://code.jquery.com/jquery-3.6.0.min.js",
    "js_pre_processor": "babel"
  }
}

Required properties

None. Simply passing an empty object will activate this feature.

Optional properties

Any valid CodePen prefill option.

Testing

To preview a small demo website, first run:

git clone https://github.com/clean-jsdoc/clean-jsdoc-es5.git
cd clean-jsdoc-es5
npm i && npm i jsdoc --no-save

On Windows, run:

npm run test:win

Otherwise:

npm test

If xdg-open is available on your system, you can build and preview the site in one step with:

npm run browse

License

Distributed under the terms of the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 599 Commits
.github		.github
demo		demo
img		img
static		static
tests		tests
tmpl		tmpl
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CODE_OF_CONDUCT_HINDI.md		CODE_OF_CONDUCT_HINDI.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
eslint.jsdoc.mjs		eslint.jsdoc.mjs
jsdoc-config.json		jsdoc-config.json
package-lock.json		package-lock.json
package.json		package.json
publish.js		publish.js

License

clean-jsdoc/clean-jsdoc-es5

Folders and files

Latest commit

History

Repository files navigation

clean-jsdoc-es5

Contents

Installation

Quick start

Workflow Integration

Options

Basic

Advanced

"project": {}

Required properties

Optional properties

"sections": [...]

Required properties

"menu": [{}, ...]

Required properties

Optional properties

"meta": [{}, ...]

Required properties

"asset_paths": ["path/to/assets", ...]

Required properties

"remote_assets": [{}, ...]

Required properties

Optional properties

"remote_scripts": [{}, ...]

Required properties

Optional properties

"overlay_scrollbar": { "options": {} }

Required properties

Optional properties

"codepen": { "options": {} }

Required properties

Optional properties

Testing

License

About

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Languages

`"project": {}`

`"sections": [...]`

`"menu": [{}, ...]`

`"meta": [{}, ...]`

`"asset_paths": ["path/to/assets", ...]`

`"remote_assets": [{}, ...]`

`"remote_scripts": [{}, ...]`

`"overlay_scrollbar": { "options": {} }`

`"codepen": { "options": {} }`