Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jaydenseric/jsdoc-md
A Node.js CLI and equivalent JS API to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as readme.md).
https://github.com/jaydenseric/jsdoc-md
babel esm jsdoc maintained markdown mjs node npm npx remark unified
Last synced: about 2 months ago
JSON representation
A Node.js CLI and equivalent JS API to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as readme.md).
- Host: GitHub
- URL: https://github.com/jaydenseric/jsdoc-md
- Owner: jaydenseric
- License: mit
- Created: 2018-06-21T14:12:09.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2022-02-01T11:19:55.000Z (over 2 years ago)
- Last Synced: 2024-06-30T21:21:50.353Z (3 months ago)
- Topics: babel, esm, jsdoc, maintained, markdown, mjs, node, npm, npx, remark, unified
- Language: JavaScript
- Homepage: https://npm.im/jsdoc-md
- Size: 1.04 MB
- Stars: 26
- Watchers: 4
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/funding.yml
- License: license.md
Awesome Lists containing this project
README
# jsdoc-md
[](https://npm.im/jsdoc-md) [](https://github.com/jaydenseric/jsdoc-md/actions)
A [Node.js](https://nodejs.org) [CLI](#cli) and equivalent JS [API](#api) to analyze source JSDoc and generate documentation under a given heading in a markdown file (such as `readme.md`).
## Installation
To install with [npm](https://npmjs.com/get-npm), run:
```sh
npm install jsdoc-md --save-dev
```
Then, use either the [CLI](#cli) command [`jsdoc-md`](#command-jsdoc-md) or the JS [API](#api) function [`jsdocMd`](#function-jsdocmd) to generate documentation.
## CLI
### Command `jsdoc-md`
Analyzes JSDoc from source files nested in the current working directory to populate a markdown file documentation section. Source files are excluded via `.gitignore` files. If the optional peer dependency [`prettier`](https://npm.im/prettier) is installed, the new markdown file contents is [Prettier](https://prettier.io) formatted.
It implements the function [`jsdocMd`](#function-jsdocmd).
#### Arguments
| Argument | Alias | Default | Description |
| :-- | :-- | :-- | :-- |
| `--source-glob` | `-s` | `**/*.{mjs,cjs,js}` | JSDoc source file glob pattern. |
| `--markdown-path` | `-m` | `readme.md` | Path to the markdown file for docs insertion. |
| `--target-heading` | `-t` | `API` | Markdown file heading to insert docs under. |
| `--check` | `-c` | | Should an error be thrown instead of updating the markdown file if the contents would change; useful for checking docs are up to date in CI. |
#### Examples
_Using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx)._
> With defaults:
>
> ```sh
> npx jsdoc-md
> ```
>
> With arguments:
>
> ```sh
> npx jsdoc-md --source-glob **/*.{mjs,cjs,js} --markdown-path readme.md --target-heading API
> ```
_Using package scripts._
> [`package.json` scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts) for a project that also uses [`eslint`](https://npm.im/eslint) and [`prettier`](https://npm.im/prettier):
>
> ```json
> {
> "scripts": {
> "docs-update": "jsdoc-md",
> "docs-check": "jsdoc-md -c",
> "eslint": "eslint .",
> "prettier": "prettier -c .",
> "test": "npm run eslint && npm run prettier && npm run docs-check",
> "prepublishOnly": "npm test"
> }
> }
> ```
>
> Run the `prettier` script before `docs-check` in the `test` script so [`prettier`](https://npm.im/prettier) reports formatting errors instead of `jsdoc-md`.
>
> Whenever the source JSDoc changes, run the `docs-update` script:
>
> ```sh
> npm run docs-update
> ```
## API
### function jsdocMd
Analyzes JSDoc from source files to populate a markdown file documentation section. Source files are excluded via `.gitignore` files. If the optional peer dependency [`prettier`](https://npm.im/prettier) is installed, the new markdown file contents is [Prettier](https://prettier.io) formatted.
| Parameter | Type | Description |
| :-- | :-- | :-- |
| `options` | object? | Options. |
| `options.cwd` | string? | A directory path to scope the search for source and `.gitignore` files, defaulting to `process.cwd()`. |
| `options.sourceGlob` | string? = `**/*.{mjs,cjs,js}` | JSDoc source file glob pattern. |
| `options.markdownPath` | string? = `readme.md` | Path to the markdown file for docs insertion. |
| `options.targetHeading` | string? = `API` | Markdown file heading to insert docs under. |
| `options.check` | boolean? = `false` | Should an error be thrown instead of updating the markdown file if the contents would change; useful for checking docs are up to date in CI. |
**Returns:** Promise\ — Resolves once the operation is done.
#### Examples
_Ways to `import`._
> ```js
> import { jsdocMd } from "jsdoc-md";
> ```
>
> ```js
> import jsdocMd from "jsdoc-md/jsdocMd.mjs";
> ```
_Customizing options._
> ```js
> jsdocMd({
> cwd: "/path/to/project",
> sourceGlob: "index.mjs",
> markdownPath: "README.md",
> targetHeading: "Docs",
> }).then(() => {
> console.log("Done!");
> });
> ```
## Caveats
### No code inference
Missing JSDoc tags are not inferred by inspecting the code, so be sure to use all the necessary tags.
```js
/**
* The number 1.
* @kind constant
* @name ONE
* @type {number}
*/
const ONE = 1;
```
### Tag subset
A JSDoc tag subset is supported:
- [`@desc`/`@description`](https://jsdoc.app/tags-description)
- [`@kind`](https://jsdoc.app/tags-kind)
- [`@name`](https://jsdoc.app/tags-name)
- [`@typedef`](https://jsdoc.app/tags-typedef)
- [`@callback`](https://jsdoc.app/tags-callback)
- [`@type`](https://jsdoc.app/tags-type)
- [`@prop`/`@property`](https://jsdoc.app/tags-property)
- [`@arg`/`@argument`/`@param`](https://jsdoc.app/tags-param)
- [`@return`/`@returns`](https://jsdoc.app/tags-returns)
- [`@emits`/`@fires`](https://jsdoc.app/tags-fires)
- [`@see`](https://jsdoc.app/tags-see)
- [`@example`](https://jsdoc.app/tags-example)
- [`@ignore`](https://jsdoc.app/tags-ignore)
### Namepath prefixes
Some [JSDoc namepath prefixes](https://jsdoc.app/about-namepaths) are not supported:
- [`module:`](https://jsdoc.app/tags-module)
- [`external:`](https://jsdoc.app/tags-external)
### Namepath special characters
[JSDoc namepath special characters](https://jsdoc.app/about-namepaths) with surrounding quotes and backslash escapes (e.g. `@name a."#b"."\"c"`) are not supported.
### Inline tags
One [JSDoc inline tag link](https://jsdoc.app/tags-inline-link) syntax is supported for namepath links in JSDoc descriptions and tags with markdown content: `` [`b` method]{@link A#b} ``. Use normal markdown syntax for non-namepath links.
Other inline tags such as [`{@tutorial}`](https://jsdoc.app/tags-inline-tutorial) are unsupported.
### Example content
[`@example`](https://jsdoc.app/tags-example) content outside `` (which may also contain markdown) is treated as markdown. This allows multiple code blocks with syntax highlighting and explanatory content such as paragraphs and images. For example:
````js
/**
* Displays a message in a native popup window.
* @kind function
* @name popup
* @param {string} message Message text.
* @example Say `Hello!` to the user.
* This usage:
*
* ```js
* popup("Hello!");
* ```
*
* Displays like this on macOS:
*
* 
*/
const popup = (message) => alert(message);
````