jsdocp

Simplified JSDoc publishing using git

Usage no npm install needed!

<script type="module">
  import jsdocp from 'https://cdn.skypack.dev/jsdocp';
</script>

README

jsdocp

npm version Build Status Dependency Status Dev Dependency Status

The links to the Tutorials and API docs below are examples of what can be generated by jsdocp:

Generated jsdoc/jsdocp pages

JSDoc publishing

jsdocp is a jsdoc/git publishing agent that generates versioned documentation, CHANGELOGs, auto-deployment to a documentation hosting service (e.g. gh-pages, etc.) and much more!

With jsdocp any number of jsdoc templates can be used for a personalized experience without the added complexities of setting up your own template extension.

Features:

Page customizations:  

  • Use virtually any JSDoc supported template- adds a responsive navigation bar to the doc pages that contains icons/links to the npm module (optional), CHANGELOG (optional), source code (optional) and doc version selection
  • Branded documentation using your own logo
  • Add your own CSS, JavaScript and meta to the documentation pages without altering the chosen template

Versioned documentation:  

  • Each time docs are tagged/deployed to GitHub or any other git supported documentation hosting service, the old docs are archived in a versioned directory
  • versions.json generation for real-time version selections in previously deployed docs (no more wiping out old docs, and old docs auto-reference an updated set of versions!)
  • Tag filtering option to restrict doc generation for tagged versions that are released for major or minor versions rather than every version that is tagged

CHANGELOG generation:  

  • Each time docs are tagged/deployed a CHANGELOG.md as well as a markdown parsed CHANGELOG.html are generated (optional)
  • Customizable CHANGELOG header and lines using markdown, git formatting (e.g. %h, etc.) and package/publishing parameter substitutions using Template Literal syntax
  • Customizable grep regular expressions for determining which commit messages will appear in the logs (including support for sub-sectioning into Breaking Changes, Features, Fixes and Merges/Pull Requests)

Documentation deployment:  

  • Page deployment execution via Node.js cli from the command line or via the provided API
  • Easy integration in continuous integration services like travis-ci, etc.

Markdown extensions:  

  • Include preprocessed source files into any of your tutorial pages. For example, if we have path/to/my/project/file.js that we want to include in a tutorial page that contains:
function sum(a, b, c) {
  return a + b + c;
}

And the following markdown is added to the page:

```jsdocp path/to/my/project/file.js
// Lets include some file sources in our docs!
```

The published docs will contain:

```js
// Lets include some file sources in our docs!
function sum(a, b, c) {
  return a + b + c;
}
```

>> Check out the Tutorials to get started (also generated by jsdocp)