tidy-jsdoc
A minimalist and clean jsdoc template.
Features
- Custom styles via CSS variables
- Code syntax highlighting via Prism.js
Preview
Note Latest Version 1.0 is considered a breaking change because the design changes significantly.
Examples
- Newton Graph Library
- Using tidy-jsdoc? Open an issue to add your documentation here.
Based on the default jsdoc template and inspired in design by vue.js documentation and docsify.
Looking for the old design?
If you want keep the old design, version your package.json appropriately. Preview old designs in the images folder.
Note: the old designs ^0.3.0 will not be updated or maintained.
Usage
Add Dependency
To use this jsdoc template in a project, first install the packages:
npm install --save-dev jsdoc tidy-jsdoc
Generate Docs
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
Configure JSDoc
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, etc. -
styles
Let's your customize colors, etc. 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
},
"plugins": [
"plugins/markdown",
"plugins/summarize"
],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
},
"metadata": {
"title": "My JavaScript Library",
}
}Customize the Template
Adjusting Theme with CSS variables
As of version 1.0, this template is styled via css variabbles, so you can adjust it to your brand. Inside your jsdoc.json configuration file, add an addional styles property, for example:
{
"metadata": "...",
"styles": {
"text-color": "#111",
"primary-color": "blue",
"heading-color": "var(--primary-color)"
}
}This would output in your document <head>:
<style>
:root {
--text-color: #111;
--primary-color: blue;
--heading-color: var(--primary-color);
}
<style>The keys and values are arbitrary, but the CSS should be valid. For a full list of the available variables, see _vars.scss.
Development
For more information about creating jsdoc templates, see the jsdoc GitHub repository.
When editing SCSS, build the CSS automatically like so:
npm run sass:watch
Note: you'll have to commit both the scss and css files.