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 }, "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'.
For more information about creating jsdoc templates, see the jsdoc GitHub repository.