{"id":13698337,"url":"https://github.com/jaydenseric/jsdoc-md","last_synced_at":"2025-05-01T04:26:32.493Z","repository":{"id":57284254,"uuid":"138179165","full_name":"jaydenseric/jsdoc-md","owner":"jaydenseric","description":"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).","archived":false,"fork":false,"pushed_at":"2022-02-01T11:19:55.000Z","size":1087,"stargazers_count":27,"open_issues_count":1,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-06T00:06:07.037Z","etag":null,"topics":["babel","esm","jsdoc","maintained","markdown","mjs","node","npm","npx","remark","unified"],"latest_commit_sha":null,"homepage":"https://npm.im/jsdoc-md","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaydenseric.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":".github/funding.yml","license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"jaydenseric"}},"created_at":"2018-06-21T14:12:09.000Z","updated_at":"2024-09-13T03:24:39.000Z","dependencies_parsed_at":"2022-09-16T22:41:28.131Z","dependency_job_id":null,"html_url":"https://github.com/jaydenseric/jsdoc-md","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2Fjsdoc-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2Fjsdoc-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2Fjsdoc-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaydenseric%2Fjsdoc-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaydenseric","download_url":"https://codeload.github.com/jaydenseric/jsdoc-md/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242728413,"owners_count":20175935,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","esm","jsdoc","maintained","markdown","mjs","node","npm","npx","remark","unified"],"created_at":"2024-08-02T19:00:44.329Z","updated_at":"2025-03-09T17:30:46.587Z","avatar_url":"https://github.com/jaydenseric.png","language":"JavaScript","readme":"![jsdoc-md logo](https://raw.githubusercontent.com/jaydenseric/jsdoc-md/a2ce08c27b4c4ffef7adc41d37f230594c17c467/jsdoc-md-logo.svg)\n\n# jsdoc-md\n\n[![npm version](https://badgen.net/npm/v/jsdoc-md)](https://npm.im/jsdoc-md) [![CI status](https://github.com/jaydenseric/jsdoc-md/workflows/CI/badge.svg)](https://github.com/jaydenseric/jsdoc-md/actions)\n\nA [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`).\n\n## Installation\n\nTo install with [npm](https://npmjs.com/get-npm), run:\n\n```sh\nnpm install jsdoc-md --save-dev\n```\n\nThen, use either the [CLI](#cli) command [`jsdoc-md`](#command-jsdoc-md) or the JS [API](#api) function [`jsdocMd`](#function-jsdocmd) to generate documentation.\n\n## CLI\n\n### Command `jsdoc-md`\n\nAnalyzes 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.\n\nIt implements the function [`jsdocMd`](#function-jsdocmd).\n\n#### Arguments\n\n| Argument | Alias | Default | Description |\n| :-- | :-- | :-- | :-- |\n| `--source-glob` | `-s` | `**/*.{mjs,cjs,js}` | JSDoc source file glob pattern. |\n| `--markdown-path` | `-m` | `readme.md` | Path to the markdown file for docs insertion. |\n| `--target-heading` | `-t` | `API` | Markdown file heading to insert docs under. |\n| `--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. |\n\n#### Examples\n\n_Using [`npx`](https://docs.npmjs.com/cli/v8/commands/npx)._\n\n\u003e With defaults:\n\u003e\n\u003e ```sh\n\u003e npx jsdoc-md\n\u003e ```\n\u003e\n\u003e With arguments:\n\u003e\n\u003e ```sh\n\u003e npx jsdoc-md --source-glob **/*.{mjs,cjs,js} --markdown-path readme.md --target-heading API\n\u003e ```\n\n_Using package scripts._\n\n\u003e [`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):\n\u003e\n\u003e ```json\n\u003e {\n\u003e   \"scripts\": {\n\u003e     \"docs-update\": \"jsdoc-md\",\n\u003e     \"docs-check\": \"jsdoc-md -c\",\n\u003e     \"eslint\": \"eslint .\",\n\u003e     \"prettier\": \"prettier -c .\",\n\u003e     \"test\": \"npm run eslint \u0026\u0026 npm run prettier \u0026\u0026 npm run docs-check\",\n\u003e     \"prepublishOnly\": \"npm test\"\n\u003e   }\n\u003e }\n\u003e ```\n\u003e\n\u003e Run the `prettier` script before `docs-check` in the `test` script so [`prettier`](https://npm.im/prettier) reports formatting errors instead of `jsdoc-md`.\n\u003e\n\u003e Whenever the source JSDoc changes, run the `docs-update` script:\n\u003e\n\u003e ```sh\n\u003e npm run docs-update\n\u003e ```\n\n## API\n\n### function jsdocMd\n\nAnalyzes 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.\n\n| Parameter | Type | Description |\n| :-- | :-- | :-- |\n| `options` | object? | Options. |\n| `options.cwd` | string? | A directory path to scope the search for source and `.gitignore` files, defaulting to `process.cwd()`. |\n| `options.sourceGlob` | string? = `**/*.{mjs,cjs,js}` | JSDoc source file glob pattern. |\n| `options.markdownPath` | string? = `readme.md` | Path to the markdown file for docs insertion. |\n| `options.targetHeading` | string? = `API` | Markdown file heading to insert docs under. |\n| `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. |\n\n**Returns:** Promise\\\u003cvoid\u003e — Resolves once the operation is done.\n\n#### Examples\n\n_Ways to `import`._\n\n\u003e ```js\n\u003e import { jsdocMd } from \"jsdoc-md\";\n\u003e ```\n\u003e\n\u003e ```js\n\u003e import jsdocMd from \"jsdoc-md/jsdocMd.mjs\";\n\u003e ```\n\n_Customizing options._\n\n\u003e ```js\n\u003e jsdocMd({\n\u003e   cwd: \"/path/to/project\",\n\u003e   sourceGlob: \"index.mjs\",\n\u003e   markdownPath: \"README.md\",\n\u003e   targetHeading: \"Docs\",\n\u003e }).then(() =\u003e {\n\u003e   console.log(\"Done!\");\n\u003e });\n\u003e ```\n\n## Caveats\n\n### No code inference\n\nMissing JSDoc tags are not inferred by inspecting the code, so be sure to use all the necessary tags.\n\n```js\n/**\n * The number 1.\n * @kind constant\n * @name ONE\n * @type {number}\n */\nconst ONE = 1;\n```\n\n### Tag subset\n\nA JSDoc tag subset is supported:\n\n- [`@desc`/`@description`](https://jsdoc.app/tags-description)\n- [`@kind`](https://jsdoc.app/tags-kind)\n- [`@name`](https://jsdoc.app/tags-name)\n- [`@typedef`](https://jsdoc.app/tags-typedef)\n- [`@callback`](https://jsdoc.app/tags-callback)\n- [`@type`](https://jsdoc.app/tags-type)\n- [`@prop`/`@property`](https://jsdoc.app/tags-property)\n- [`@arg`/`@argument`/`@param`](https://jsdoc.app/tags-param)\n- [`@return`/`@returns`](https://jsdoc.app/tags-returns)\n- [`@emits`/`@fires`](https://jsdoc.app/tags-fires)\n- [`@see`](https://jsdoc.app/tags-see)\n- [`@example`](https://jsdoc.app/tags-example)\n- [`@ignore`](https://jsdoc.app/tags-ignore)\n\n### Namepath prefixes\n\nSome [JSDoc namepath prefixes](https://jsdoc.app/about-namepaths) are not supported:\n\n- [`module:`](https://jsdoc.app/tags-module)\n- [`external:`](https://jsdoc.app/tags-external)\n\n### Namepath special characters\n\n[JSDoc namepath special characters](https://jsdoc.app/about-namepaths) with surrounding quotes and backslash escapes (e.g. `@name a.\"#b\".\"\\\"c\"`) are not supported.\n\n### Inline tags\n\nOne [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.\n\nOther inline tags such as [`{@tutorial}`](https://jsdoc.app/tags-inline-tutorial) are unsupported.\n\n### Example content\n\n[`@example`](https://jsdoc.app/tags-example) content outside `\u003ccaption /\u003e` (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:\n\n````js\n/**\n * Displays a message in a native popup window.\n * @kind function\n * @name popup\n * @param {string} message Message text.\n * @example \u003ccaption\u003eSay `Hello!` to the user.\u003c/caption\u003e\n * This usage:\n *\n * ```js\n * popup(\"Hello!\");\n * ```\n *\n * Displays like this on macOS:\n *\n * ![Screenshot](path/to/screenshot.jpg)\n */\nconst popup = (message) =\u003e alert(message);\n````\n","funding_links":["https://github.com/sponsors/jaydenseric"],"categories":["Markdown"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenseric%2Fjsdoc-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaydenseric%2Fjsdoc-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaydenseric%2Fjsdoc-md/lists"}