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 highly customizable theme (for more look below in feature section).
Feel free to raise issues.
- Demo
- Technologies Used
- Motivation
- Install
- Usage
- Nodejs Dependencies
- Example Jsdoc Config
- Features
- Changelog
- Developing
- Contributors
- Contact
- License
Live demo (dark): https://ankdev.me/clean-jsdoc-theme/dark/index.html
Live demo (light): https://ankdev.me/clean-jsdoc-theme/light/index.html
- Fuse.js - Fuse.js is a powerful, lightweight fuzzy-search library, with zero dependencies. Learn More
- Overlay Scrollbars - A javascript scrollbar plugin which hides native scrollbars, provides custom styleable overlay scrollbars and keeps the native functionality and feeling. Learn More
- Nodejs
At the time when I was new to js documentation and jsdoc, it was hard for me to find any theme for jsdoc which is highly customizable or regularly maintaining. Also, the search used in other themes is not that advanced. To tackle these I created this project. I am actively listening to the community and try to make the changes as soon as possible.
Note you must have
npm
installed on your machine.
On your command line type
npm install clean-jsdoc-theme
Clone repository to your designated jsdoc template directory, then
jsdoc entry-file.js -t path/to/clean-jsdoc-theme
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"
}
{
"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",
"theme_opts": {
"theme": "dark"
}
}
}
You can pass an object called theme_opts
under opts
for more options.
To set the overall theme of the documentation file(s). Currently there is only two variant "light"
and "dark"
but in future I will try to add more.
Default value is "light"
To set the title to the navbar. String and HTMl is both accepted. Use HTML to overwrite the default HTML. You can do something like this
"title": "<img src='path/to/img' class='my-custom-class'/>"
You can use static_dir
to copy all you static files to output dir and use that path in place of path/to/img
. For more details look static_dir
section.
This is deprecated. This is used to turn the navbar image to white for better contrast.
To render extra link(s) in navbar. It accepts an array of objects example:
"menu" : [
{
"title": "Website",
"link": "https://ankdev.me/clean-jsdoc-theme/dark/",
"target": "_blank",
"class": "some-class",
"id": "some-id"
}
]
name | type |
---|---|
title |
string |
link |
string |
name | type |
---|---|
target |
string |
class |
string |
id |
string |
A list of meta
tag attributes to add to the head
of each page.
"meta" : [
{
"name": "author",
"content": "Ankit Kumar"
},
{
"name": "description",
"content": "Best Clean and minimal JSDoc 3 Template/Theme"
}
]
Any valid combination of HTML metadata attributes.
To render search. Default value:
"search": {
"shouldSort": true,
"threshold": 0.4,
"location": 0,
"distance": 100,
"maxPatternLength": 32,
"minMatchCharLength": 1,
}
Any valid fuse.js properties
Includes the OverlayScrollbars plugin. Simply passing an empty object will activate this feature.
"overlay_scrollbar": {
"option": {}
}
Any valid overlay scrollbar properties
To create custom style rules. Example:
"create_style": "nav{background: yellow} footer {background: green}"
Here the nav and footer style rule is to attached to the HTML's style
tag.
To create custom scripts. Example:
"create_style": "function foo(){console.log('foo')} function bar() {console.log('bar')}"
Here the script is to attached to the HTML's script
tag.
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.
Example:
"add_style_path": [
{
"href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css",
"integrity": "sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1",
"crossorigin": "anonymous"
}
],
Any valid style tag attributes
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.
Example:
"add_script_path": [
{
"href": "https://code.jquery.com/jquery-3.5.1.js",
"integrity": "sha256-QWo7LDvxbWT2tbbQ97B53yJnYU3WhH/C8ycbRAkjPDc=",
"crossorigin": "anonymous"
}
],
Any valid script tag attributes
Thing which you want to render as the footer. You can either pass a string or HTML. Use HTML to overwrite the default HTML.
"footer": "This is footer"
To include static files. Example:
"static_dir": ["./static"],
This will copy the static folder to the output dir.
Note: If the directory doesn't exists then you may get an error. Also directory is relative to your jsdoc config file.
This will not flatten then directory it keep the directory structure as it is.
To include css files. Example:
"include_css": ["./static/index.css", "./src/docs/index.css"]
Note: You are not required to manually copy file to output dir
It will include the css files to the output dir and also attache a link tag to the html pointing to the included css file.
To include js files. Example:
"include_js": ["./static/index.js", "./src/docs/index.js"]
Note: You are not required to manually copy file to output dir
It will include the js files to the output dir and also attache a link tag to the html pointing to the included js file.
"opts":{
"theme_opts":{
"theme": "dark",
"title": "clean-jsdoc-theme",
"filter": false,
"menu": [
{
"title": "Website",
"link": "https://ankdev.me/clean-jsdoc-theme/index.html",
"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"
}
],
"meta": [
{
"name": "author",
"content": "Ankit Kumar"
},
{
"name": "description",
"content": "Best Clean and minimal JSDoc 3 Template/Theme"
}
],
"search": {},
"create_style": "nav{background: yellow}",
"add_style_path": [
{
"href": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css",
"integrity": "sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1",
"crossorigin": "anonymous"
}
],
"add_scripts": "function foo(){console.log('foo')}",
"add_script_path": [
{
"src": "https://code.jquery.com/jquery-3.5.1.js",
"integrity": "sha256-QWo7LDvxbWT2tbbQ97B53yJnYU3WhH/C8ycbRAkjPDc=",
"crossorigin": "anonymous"
}
],
"footer": "This is footer",
"static_dir": ["./static"],
"include_css": ["./static/index.css", "./src/docs/index.css"],
"include_js": ["./static/main.js", "./third-party/test/index.js"],
"overlay_scrollbar": {
"options": {
}
}
}
}
name | default | use case | expected value(s) |
---|---|---|---|
theme |
"light" |
To set the theme variant | "light" or "dark" |
title |
null |
To set the title | HTML or string |
filter |
false |
Turn the navbar image to white | boolean |
menu |
null |
To render extra link in navbar | Array of Object(s) |
meta |
null |
Meta tag attributes | Array of Object(s) |
search |
{} |
To render search or not | Fuse.js options |
create_style |
null |
To create custom style rules | string |
add_style_path |
null |
To add external css libraries/files | Array of Object(s) |
add_scripts |
null |
To create custom script | string |
add_script_path |
null |
To add external js libraries/files | Array of Object(s) |
footer |
null |
To render footer | HTML or string |
static_dir |
null |
To include static dir | Array of string |
include_css |
null |
To include css files | Array of string |
include_js |
null |
To include js files | string |
overlay_scrollbar |
null |
To use overlay scrollbar | Overlay Scrollbar options |
Changelog is moved to https://github.com/ankitskvmdam/clean-jsdoc-theme/blob/master/CHANGELOG.md
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.
If you like my work, then give me a star. This will act as a driving force to add new feature more frequently.
Mail me at: [email protected]
Licensed under the MIT license.