@appku/jsdoc-template

v1.1.10

Published

a month ago

A clean JSDoc3 template

Downloads

0High
0Medium
0Low

chriseaton

jsdoc template

jsdoc-template

A minimalist and clean jsdoc template.

Features

Custom styles via CSS variables
Code syntax highlighting via Prism.js

Examples

Newton Graph Library
Using @appku/jsdoc-template? Open an issue to add your documentation here.

Based on the default jsdoc template and inspired in design by vue.js documentation and docsify.

Usage

Add Dependency

To use this jsdoc template in a project, first install the packages:

npm install --save-dev jsdoc @appku/jsdoc-template

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/@appku/jsdoc-template
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/@appku/jsdoc-template",
    "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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme