0
# JSDoc to Markdown
1

2
JSDoc to Markdown is a comprehensive tool for generating markdown API documentation from JSDoc-annotated JavaScript source code. It serves as a bridge between JSDoc comments in source files and markdown documentation, making it particularly useful for injecting API documentation into project README files and maintaining up-to-date documentation. The library offers both programmatic API access and command-line interface, supporting various output formats and customization options.
3

4
## Package Information
5

6
- **Package Name**: jsdoc-to-markdown
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install --save-dev jsdoc-to-markdown`
10

11
## Core Imports
12

13
```javascript
14
import jsdoc2md from 'jsdoc-to-markdown';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const jsdoc2md = require('jsdoc-to-markdown');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import jsdoc2md from 'jsdoc-to-markdown';
27

28
// Generate markdown from JavaScript files
29
const apiDocs = await jsdoc2md.render({ files: 'lib/*.js' });
30

31
// Generate from source code string
32
const apiDocs = await jsdoc2md.render({
33
  source: `
34
    /**
35
     * A wonderful function.
36
     * @param {object} config - Configuration object
37
     * @returns {string} Formatted output
38
     */
39
    function formatData(config) {
40
      return 'formatted';
41
    }
42
  `
43
});
44

45
// Get raw JSDoc data
46
const jsdocData = await jsdoc2md.getJsdocData({ files: 'src/*.js' });
47

48
// Get template data for custom processing
49
const templateData = await jsdoc2md.getTemplateData({ files: 'src/*.js' });
50
```
51

52
## Architecture
53

54
JSDoc to Markdown is built around several key components:
55

56
- **Core API**: Main `JsdocToMarkdown` class providing all functionality through a singleton instance
57
- **JSDoc Integration**: Leverages `jsdoc-api` for parsing JSDoc annotations
58
- **Template Engine**: Uses `dmd` (Documentation Markdown) for rendering markdown output
59
- **CLI Interface**: Full-featured command-line tool with extensive configuration options
60
- **Caching System**: Built-in caching for improved performance on repeated invocations
61
- **Option Processing**: Separate classes for handling different configuration contexts
62

63
## Capabilities
64

65
### Programmatic API
66

67
Core programmatic interface for generating markdown documentation from JSDoc-annotated source code. Provides methods for rendering, data extraction, and cache management.
68

69
```javascript { .api }
70
async function render(options?: RenderOptions): Promise<string>;
71
async function getTemplateData(options?: TemplateDataOptions): Promise<object[]>;
72
async function getJsdocData(options: JsdocDataOptions): Promise<object[]>;
73
async function clear(): Promise<void>;
74
async function getNamepaths(options: NamepathOptions): Promise<object>;
75
```
76

77
[Programmatic API](./programmatic-api.md)
78

79
### Command Line Interface
80

81
Comprehensive CLI tool for generating documentation with extensive configuration options, multiple output formats, and configuration file support.
82

83
```bash { .api }
84
# Basic usage
85
jsdoc2md src/*.js
86

87
# With options
88
jsdoc2md --files src/*.js --heading-depth 1 --template custom.hbs
89

90
# Different output modes
91
jsdoc2md --files src/*.js --json          # Raw template data
92
jsdoc2md --files src/*.js --jsdoc         # Raw JSDoc data
93
jsdoc2md --files src/*.js --namepaths     # Namepath information
94
```
95

96
[Command Line Interface](./cli.md)
97

98
## Types
99

100
```javascript { .api }
101
interface RenderOptions extends TemplateDataOptions {
102
  /** Raw template data to use instead of parsing files */
103
  data?: object[];
104
  /** Custom handlebars template for full control over output */
105
  template?: string;
106
  /** Initial heading depth (default: 2) */
107
  'heading-depth'?: number;
108
  /** Default language for @example blocks */
109
  'example-lang'?: string;
110
  /** Installed package containing helper/partial overrides */
111
  plugin?: string | string[];
112
  /** Handlebars helper files to override defaults */
113
  helper?: string | string[];
114
  /** Handlebars partial files to override defaults */
115
  partial?: string | string[];
116
  /** Format identifier names as code (wrap in backticks) */
117
  'name-format'?: boolean;
118
  /** Disable GitHub-flavored markdown */
119
  'no-gfm'?: boolean;
120
  /** Add horizontal rule breaks between identifiers */
121
  separators?: boolean;
122
  /** Module index format: none, grouped, table, dl */
123
  'module-index-format'?: string;
124
  /** Global index format: none, grouped, table, dl */
125
  'global-index-format'?: string;
126
  /** Parameter list format: list, table */
127
  'param-list-format'?: string;
128
  /** Property list format: list, table */
129
  'property-list-format'?: string;
130
  /** Member index format: grouped, list */
131
  'member-index-format'?: string;
132
  /** Render URL links in plain text, others in monospace */
133
  'clever-links'?: boolean;
134
  /** Render all links in monospace */
135
  'monospace-links'?: boolean;
136
  /** EOL character: posix, win32 */
137
  EOL?: string;
138
}
139

140
interface TemplateDataOptions extends JsdocDataOptions {}
141

142
interface JsdocDataOptions {
143
  /** Disable caching for this invocation */
144
  'no-cache'?: boolean;
145
  /** File paths or glob patterns to process */
146
  files?: string | string[];
147
  /** Source code string to process */
148
  source?: string;
149
  /** Path to JSDoc configuration file */
150
  configure?: string;
151
}
152

153
interface NamepathOptions extends TemplateDataOptions {}
154
```