A minimalist and clean jsdoc template.
Forked from tidy-jsdoc.
- Custom styles via CSS variables
- Code syntax highlighting via Prism.js
Based on the default jsdoc template and inspired in design by vue.js documentation and docsify.
To use this jsdoc template in a project, first install the packages:
npm install --save-dev jsdoc JamesNZL/tidy-jsdoc
Once you've configured jsdoc and added syntax to your JavaScript files, you can generate the HTML files like so, optionally including a readme file:
jsdoc --readme README.md -c jsdoc.json
Then configure jsdoc to use the tidy template. Below is an example jsdoc.json configuration file. Be sure to adjust
-
template
Points to./node_modules/tidy-jsdoc -
prism-theme
Optionally pick a prismjs theme for styling your code. Defaults to "prism-tomorrow-night". Choose from templates available in./static/styles/vendor/folder -
destination
Output is./docs/, allowing for easy GitHub Pages publishing. -
metadata
Customize title, logo, favicon, etc. -
styles
Lets you customise colours, etc. See details below. -
menu
Lets you implement custom navigation links at the top of the side bar. See details below. -
repository
Lets you add links to your source files in your Git repositories. See details below.
{
"tags": {
"allowUnknownTags": true,
"dictionaries": [
"jsdoc",
"closure"
]
},
"source": {
"include": [
"src"
],
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"opts": {
"template": "./node_modules/tidy-jsdoc",
"prism-theme": "prism-custom",
"encoding": "utf8",
"destination": "./docs/",
"recurse": true,
"showTypedefsInNav": false,
},
"plugins": [
"plugins/markdown",
"plugins/summarize"
],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"metadata": {
"title": "My JavaScript Library",
},
"menu": [
{
"title": "GitHub Repository",
"link": "https://github.com/JamesNZL/tidy-jsdoc",
"target": "_blank"
}
],
"repository": {
"link": "https://github.com/JamesNZL/tidy-jsdoc",
"branch": "main",
"type": "GitHub"
}
}This template is styled via CSS variables, so you can adjust it to your brand. Inside your jsdoc.json configuration file, add an addional styles property, for example:
{
"metadata": "...",
"styles": {
"text-colour": "#111",
"primary-colour": "blue",
"heading-colour": "var(--primary-colour)"
}
}This would output in your document <head>:
<style>
:root {
--text-colour: #111;
--primary-colour: blue;
--heading-colour: var(--primary-colour);
}
<style>The keys and values are arbitrary, but the CSS should be valid. For a full list of the available variables, see styles.css.
Inside your jsdoc.json configuration file, add an addional menu property, for example:
{
"metadata": "...",
"menu": [
{
"title": "GitHub Repository",
"link": "https://github.com/JamesNZL/tidy-jsdoc",
"target": "_blank"
}
]
}This would output a link at the top of your navigation sidebar:
<a href="https://github.com/JamesNZL/tidy-jsdoc" target="_blank">GitHub Repository</a>The menu property must be of the following type:
{
title: string,
link: string,
target: ?string
}[]Inside your jsdoc.json configuration file, add an addional repository property, for example:
{
"metadata": "...",
"repository": {
"link": "https://github.com/JamesNZL/tidy-jsdoc",
"branch": "main",
"type": "GitHub"
}
}If type is specified, the link text will render as View on ${type}, e.g. 'View on Github'. If it is omitted or blank, it will render as 'View in Repository'.
Inside the opts object of your jsdoc.json configuration file, set the property showTypedefsInNav to true.
For more information about creating jsdoc templates, see the jsdoc GitHub repository.