https://github.com/julie-ng/tidy-jsdoc
A clean JSDoc3 template
https://github.com/julie-ng/tidy-jsdoc
api docs documentation jsdoc jsdoc-template
Last synced: 4 months ago
JSON representation
A clean JSDoc3 template
- Host: GitHub
- URL: https://github.com/julie-ng/tidy-jsdoc
- Owner: julie-ng
- License: other
- Created: 2017-05-06T13:21:36.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2022-12-02T01:06:26.000Z (almost 3 years ago)
- Last Synced: 2025-05-25T08:49:49.528Z (5 months ago)
- Topics: api, docs, documentation, jsdoc, jsdoc-template
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/tidy-jsdoc
- Size: 1.93 MB
- Stars: 26
- Watchers: 3
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# tidy-jsdoc
[](https://travis-ci.org/julie-ng/tidy-jsdoc)
[](https://snyk.io//test/github/julie-ng/tidy-jsdoc?targetFile=package.json)
A minimalist and clean [jsdoc](https://jsdoc.app/index.html) template.
### Features
- Custom styles via [CSS variables](#adjusting-theme-with-css-variables)
- Code syntax highlighting via [Prism.js](https://prismjs.com/)
## Preview
Note Latest Version 1.0 is considered a _breaking change_ because the design changes significantly.
#### Examples
- [Newton Graph Library](https://julie-ng.github.io/newtonjs-graph/)
- Using tidy-jsdoc? Open an issue to add your documentation here.
Based on the [default jsdoc template](https://github.com/jsdoc/jsdoc/tree/master/templates) and inspired in design by [vue.js documentation](https://vuejs.org/v2/api/) and [docsify](https://docsify.js.org).
#### Looking for the old design?
If you want keep the old design, version your `package.json` appropriately. Preview old designs in the [images folder](./images/).
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/`](./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.
```javascript
{
"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:
```javascript
{
"metadata": "...",
"styles": {
"text-color": "#111",
"primary-color": "blue",
"heading-color": "var(--primary-color)"
}
}
```
This would output in your document ``:
```html
: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](./static/styles/_vars.scss).
## Development
For more information about creating jsdoc templates, see the [jsdoc GitHub repository](https://github.com/jsdoc/jsdoc/tree/master/templates).
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.