0
# Minami
1

2
Minami is a clean, responsive documentation template theme for JSDoc 3 that generates professional-looking documentation websites from JSDoc comments. It provides a complete theming solution with modern typography, syntax highlighting, and responsive design.
3

4
## Package Information
5

6
- **Package Name**: minami
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev minami`
10

11
## Core Imports
12

13
Minami is a JSDoc template, not a library to import. It's configured in JSDoc configuration files:
14

15
```json
16
{
17
  "opts": {
18
    "template": "node_modules/minami"
19
  }
20
}
21
```
22

23
## Basic Usage
24

25
Install and configure minami as your JSDoc template:
26

27
```bash
28
npm install --save-dev minami
29
```
30

31
Create a `.jsdoc.json` configuration file:
32

33
```json
34
{
35
  "tags": {
36
    "allowUnknownTags": true,
37
    "dictionaries": ["jsdoc"]
38
  },
39
  "source": {
40
    "include": ["lib", "package.json", "README.md"],
41
    "includePattern": ".js$",
42
    "excludePattern": "(node_modules/|docs)"
43
  },
44
  "plugins": ["plugins/markdown"],
45
  "templates": {
46
    "cleverLinks": false,
47
    "monospaceLinks": true,
48
    "useLongnameInNav": false,
49
    "showInheritedInNav": true
50
  },
51
  "opts": {
52
    "destination": "./docs/",
53
    "encoding": "utf8",
54
    "private": true,
55
    "recurse": true,
56
    "template": "./node_modules/minami"
57
  }
58
}
59
```
60

61
Generate documentation:
62

63
```bash
64
npx jsdoc --configure .jsdoc.json --verbose
65
```
66

67
## Architecture
68

69
Minami is structured as a JSDoc template with the following components:
70

71
- **Template Publisher**: Main `exports.publish` function that processes JSDoc data
72
- **Template Files**: HTML templates for different documentation sections
73
- **Static Assets**: CSS styles, JavaScript utilities, and web fonts
74
- **Navigation Builder**: Dynamic navigation generation based on doclet structure
75
- **Content Generators**: Functions for creating individual documentation pages
76

77
## Capabilities
78

79
### JSDoc Template Publisher
80

81
Main entry point called by JSDoc to generate documentation from parsed doclets.
82

83
```javascript { .api }
84
/**
85
 * Main JSDoc template publish function called by JSDoc to generate documentation
86
 * @param {TAFFY} taffyData - JSDoc data in TaffyDB format containing all doclets
87
 * @param {Object} opts - Template and JSDoc options including destination and encoding  
88
 * @param {Tutorial} tutorials - JSDoc tutorials data for generating tutorial pages
89
 */
90
exports.publish = function(taffyData, opts, tutorials);
91
```
92

93
This is the primary interface that JSDoc calls when using minami as a template. It processes all parsed documentation data and generates HTML files.
94

95
### Template Configuration
96

97
Minami supports extensive configuration through JSDoc's template options.
98

99
```javascript { .api }
100
interface TemplateOptions {
101
  /** Enable intelligent linking for references */
102
  cleverLinks?: boolean;
103
  /** Use monospace font for code links */
104
  monospaceLinks?: boolean;
105
  /** Show long names in navigation or max path elements to show */
106
  useLongnameInNav?: boolean | number;
107
  /** Show inherited members in navigation */
108
  showInheritedInNav?: boolean;
109
}
110

111
interface JsDocOptions {
112
  /** Output directory for generated documentation */
113
  destination: string;
114
  /** File encoding for generated files */
115
  encoding?: string;
116
  /** Include private members in documentation */
117
  private?: boolean;
118
  /** Recurse into subdirectories */
119
  recurse?: boolean;
120
  /** Path to template directory */
121
  template: string;
122
}
123
```
124

125
### Template Assets
126

127
Minami includes comprehensive template and static assets for documentation generation.
128

129
```javascript { .api }
130
interface TemplateAssets {
131
  /** HTML templates for different documentation sections */
132
  templates: {
133
    "layout.tmpl": "Main page layout template";
134
    "container.tmpl": "Container template for content sections";
135
    "mainpage.tmpl": "Homepage/index template";
136
    "members.tmpl": "Template for class/namespace members";
137
    "method.tmpl": "Template for function/method documentation";
138
    "properties.tmpl": "Template for property documentation";
139
    "params.tmpl": "Template for parameter documentation";
140
    "returns.tmpl": "Template for return value documentation";
141
    "details.tmpl": "Template for detailed information sections";
142
    "type.tmpl": "Template for type information";
143
    "examples.tmpl": "Template for code examples";
144
    "example.tmpl": "Template for individual example";
145
    "tutorial.tmpl": "Template for tutorial pages";
146
    "source.tmpl": "Template for source code display";
147
    "augments.tmpl": "Template for inheritance information";
148
    "exceptions.tmpl": "Template for exception documentation";
149
  };
150
  
151
  /** CSS stylesheets for documentation appearance */
152
  styles: {
153
    "jsdoc-default.css": "Main stylesheet for the template";
154
    "prettify-jsdoc.css": "Stylesheet for code syntax highlighting integration";
155
    "prettify-tomorrow.css": "Tomorrow theme for code highlighting";
156
  };
157
  
158
  /** JavaScript utilities for enhanced functionality */
159
  scripts: {
160
    "linenumber.js": "Script for adding line numbers to code blocks";
161
    "prettify.js": "Google Prettify library for syntax highlighting";
162
    "lang-css.js": "CSS language support for Prettify";
163
  };
164
  
165
  /** OpenSans font files in various formats */
166
  fonts: {
167
    "OpenSans-Regular-webfont.eot": "Regular weight EOT format";
168
    "OpenSans-Regular-webfont.woff": "Regular weight WOFF format";
169
    "OpenSans-Regular-webfont.svg": "Regular weight SVG format";
170
    "OpenSans-Bold-webfont.eot": "Bold weight EOT format";
171
    "OpenSans-Bold-webfont.woff": "Bold weight WOFF format";
172
    "OpenSans-Bold-webfont.svg": "Bold weight SVG format";
173
    "OpenSans-BoldItalic-webfont.eot": "Bold italic EOT format";
174
    "OpenSans-BoldItalic-webfont.woff": "Bold italic WOFF format";
175
    "OpenSans-BoldItalic-webfont.svg": "Bold italic SVG format";
176
    "OpenSans-Italic-webfont.eot": "Italic EOT format";
177
    "OpenSans-Italic-webfont.woff": "Italic WOFF format";
178
    "OpenSans-Italic-webfont.svg": "Italic SVG format";
179
    "OpenSans-Light-webfont.eot": "Light weight EOT format";
180
    "OpenSans-Light-webfont.woff": "Light weight WOFF format";
181
    "OpenSans-Light-webfont.svg": "Light weight SVG format";
182
    "OpenSans-LightItalic-webfont.eot": "Light italic EOT format";
183
    "OpenSans-LightItalic-webfont.woff": "Light italic WOFF format";
184
    "OpenSans-LightItalic-webfont.svg": "Light italic SVG format";
185
    "OpenSans-Semibold-webfont.eot": "Semibold weight EOT format";
186
    "OpenSans-Semibold-webfont.woff": "Semibold weight WOFF format";
187
    "OpenSans-Semibold-webfont.svg": "Semibold weight SVG format";
188
    "OpenSans-Semibold-webfont.ttf": "Semibold weight TTF format";
189
    "OpenSans-SemiboldItalic-webfont.eot": "Semibold italic EOT format";
190
    "OpenSans-SemiboldItalic-webfont.woff": "Semibold italic WOFF format";
191
    "OpenSans-SemiboldItalic-webfont.svg": "Semibold italic SVG format";
192
    "OpenSans-SemiboldItalic-webfont.ttf": "Semibold italic TTF format";
193
  };
194
}
195
```
196

197
### Navigation Generation
198

199
Builds hierarchical navigation sidebar from JSDoc member data.
200

201
```javascript { .api }
202
/**
203
 * Create the navigation sidebar HTML
204
 * @param {Object} members - The members that will be used to create the sidebar
205
 * @param {Array} members.classes - Class doclets
206
 * @param {Array} members.externals - External doclets  
207
 * @param {Array} members.globals - Global doclets
208
 * @param {Array} members.mixins - Mixin doclets
209
 * @param {Array} members.modules - Module doclets
210
 * @param {Array} members.namespaces - Namespace doclets
211
 * @param {Array} members.tutorials - Tutorial doclets
212
 * @param {Array} members.events - Event doclets
213
 * @param {Array} members.interfaces - Interface doclets
214
 * @returns {string} The HTML for the navigation sidebar
215
 */
216
function buildNav(members);
217
```
218

219
### Page Generation
220

221
Generates individual HTML pages for different documentation types.
222

223
```javascript { .api }
224
/**
225
 * Generate an HTML documentation page
226
 * @param {string} type - The type of page being generated
227
 * @param {string} title - The page title
228
 * @param {Array} docs - Array of doclets to include in the page
229
 * @param {string} filename - Output filename for the generated page
230
 * @param {boolean} resolveLinks - Whether to resolve JSDoc link references (default: true)
231
 */
232
function generate(type, title, docs, filename, resolveLinks);
233

234
/**
235
 * Generate source code view pages
236
 * @param {Object} sourceFiles - Object mapping file paths to source file data
237
 * @param {string} encoding - File encoding to use when reading source files (default: "utf8")
238
 */
239
function generateSourceFiles(sourceFiles, encoding);
240

241
/**
242
 * Generate tutorial pages from JSDoc tutorial data (internal function)
243
 * @param {string} title - Tutorial title
244
 * @param {Object} tutorial - Tutorial object with content and metadata
245
 * @param {string} filename - Output filename for the tutorial page
246
 */
247
function generateTutorial(title, tutorial, filename);
248
```
249

250
### Doclet Processing
251

252
Utilities for processing and enhancing JSDoc doclets with template-specific formatting.
253

254
```javascript { .api }
255
/**
256
 * Find doclets matching specification (wrapper around helper.find)
257
 * @param {Object} spec - Query specification object
258
 * @returns {Array} Array of matching doclets
259
 */
260
function find(spec);
261

262
/**
263
 * Determine if doclet needs function signature
264
 * @param {Object} doclet - JSDoc doclet object
265
 * @returns {boolean} True if signature is needed
266
 */
267
function needsSignature(doclet);
268

269
/**
270
 * Add parameter signature to function doclet
271
 * @param {Object} f - Function doclet to enhance
272
 */
273
function addSignatureParams(f);
274

275
/**
276
 * Add return type signature to function doclet
277
 * @param {Object} f - Function doclet to enhance  
278
 */
279
function addSignatureReturns(f);
280

281
/**
282
 * Add type signature to member doclet
283
 * @param {Object} f - Member doclet to enhance
284
 */
285
function addSignatureTypes(f);
286

287
/**
288
 * Add attributes to doclet for display
289
 * @param {Object} f - Doclet to enhance with attributes
290
 */
291
function addAttribs(f);
292

293
/**
294
 * Get signature attributes for a doclet item
295
 * @param {Object} item - Doclet item to process
296
 * @returns {Array} Array of attribute strings
297
 */
298
function getSignatureAttributes(item);
299

300
/**
301
 * Update item name with signature attributes
302
 * @param {Object} item - Item to update
303
 * @returns {string} Updated item name with attributes
304
 */
305
function updateItemName(item);
306

307
/**
308
 * Add parameter attributes to parameters array
309
 * @param {Array} params - Parameters to process
310
 * @returns {Array} Processed parameter names
311
 */
312
function addParamAttributes(params);
313

314
/**
315
 * Build type strings for display
316
 * @param {Object} item - Item with type information
317
 * @returns {Array} Array of type strings
318
 */
319
function buildItemTypeStrings(item);
320

321
/**
322
 * Build attributes string for display
323
 * @param {Array} attribs - Array of attributes
324
 * @returns {string} Formatted attributes string
325
 */
326
function buildAttribsString(attribs);
327

328
/**
329
 * Add non-parameter attributes to items
330
 * @param {Array} items - Items to process
331
 * @returns {Array} Array of type strings
332
 */
333
function addNonParamAttributes(items);
334

335
/**
336
 * Process tutorial children recursively (internal function)
337
 * @param {Object} node - Tutorial node with children
338
 */
339
function saveChildren(node);
340
```
341

342
### Link and Path Utilities
343

344
Helper functions for generating links and managing file paths in documentation.
345

346
```javascript { .api }
347
/**
348
 * Create tutorial link HTML
349
 * @param {string} tutorial - Tutorial identifier
350
 * @returns {string} HTML link to tutorial
351
 */
352
function tutoriallink(tutorial);
353

354
/**
355
 * Get ancestor links for doclet inheritance chain
356
 * @param {Object} doclet - JSDoc doclet object
357
 * @returns {Array} Array of ancestor link objects
358
 */
359
function getAncestorLinks(doclet);
360

361
/**
362
 * Convert hash reference to clickable link
363
 * @param {Object} doclet - Context doclet for link resolution
364
 * @param {string} hash - Hash reference to convert
365
 * @returns {string} HTML link element
366
 */
367
function hashToLink(doclet, hash);
368

369
/**
370
 * Shorten file paths for display by removing common prefix
371
 * @param {Object} files - Object mapping file paths to file data
372
 * @param {string} commonPrefix - Common prefix to remove from paths
373
 * @returns {Object} Files object with shortened paths added
374
 */
375
function shortenPaths(files, commonPrefix);
376

377
/**
378
 * Extract file path from doclet metadata
379
 * @param {Object} doclet - JSDoc doclet with meta information
380
 * @returns {string|null} File path or null if no path available
381
 */
382
function getPathFromDoclet(doclet);
383

384
/**
385
 * Attach module symbols to module doclets (mutates original arrays)
386
 * @param {Array} doclets - Array of classes and functions to check
387
 * @param {Array} modules - Array of module doclets to search
388
 * @returns {Array} Modified modules array with attached symbols
389
 */
390
function attachModuleSymbols(doclets, modules);
391

392
/**
393
 * Build member navigation for a specific item type
394
 * @param {Array} items - Items to build navigation for
395
 * @param {string} itemHeading - Heading text for the item section
396
 * @param {Object} itemsSeen - Object tracking which items have been processed
397
 * @param {Function} linktoFn - Function to generate links for items
398
 * @returns {Array} Navigation HTML elements
399
 */
400
function buildMemberNav(items, itemHeading, itemsSeen, linktoFn);
401

402
/**
403
 * Generate navigation link wrapper
404
 * @param {string} linkClass - CSS class for the navigation link
405
 * @param {string} linkContent - HTML content for the link
406
 * @returns {string} HTML list item with navigation link
407
 */
408
function buildNavLink(linkClass, linkContent);
409

410
/**
411
 * Generate navigation heading wrapper
412
 * @param {string} content - Navigation header content
413
 * @returns {string} HTML list item with navigation heading
414
 */
415
function buildNavHeading(content);
416

417
/**
418
 * Generate navigation item wrapper
419
 * @param {string} itemContent - Navigation item content
420
 * @returns {string} HTML list item with navigation item
421
 */
422
function buildNavItem(itemContent);
423

424
/**
425
 * Generate navigation type indicator
426
 * @param {string} type - Type of the navigation item (function, class, etc.)
427
 * @param {string} typeLink - Link HTML for the type
428
 * @returns {string} HTML with type indicator and link
429
 */
430
function buildNavType(type, typeLink);
431

432
/**
433
 * Link to tutorial helper function
434
 * @param {string} longName - Tutorial long name
435
 * @param {string} name - Tutorial display name
436
 * @returns {string} Tutorial link HTML
437
 */
438
function linktoTutorial(longName, name);
439

440
/**
441
 * Link to external helper function
442
 * @param {string} longName - External long name
443
 * @param {string} name - External display name
444
 * @returns {string} External link HTML
445
 */
446
function linktoExternal(longName, name);
447
```
448

449
## Types
450

451
```javascript { .api }
452
/** JSDoc doclet object containing parsed documentation data */
453
interface Doclet {
454
  /** Doclet kind (function, class, member, etc.) */
455
  kind: string;
456
  /** Full qualified name */
457
  longname: string;
458
  /** Short name */
459
  name: string;
460
  /** Description text */
461
  description?: string;
462
  /** Parameter information for functions */
463
  params?: Array<{
464
    name: string;
465
    type?: { names: string[] };
466
    description?: string;
467
    optional?: boolean;
468
    nullable?: boolean;
469
    variable?: boolean;
470
  }>;
471
  /** Return value information */
472
  returns?: Array<{
473
    type?: { names: string[] };
474
    description?: string;
475
  }>;
476
  /** Code examples */
477
  examples?: string[];
478
  /** See also references */
479
  see?: string[];
480
  /** File metadata */
481
  meta?: {
482
    path: string;
483
    filename: string;
484
    shortpath?: string;
485
  };
486
  /** Inheritance information */
487
  ancestors?: Array<{ name: string; url: string }>;
488
  /** Generated signature HTML */
489
  signature?: string;
490
  /** Generated attributes HTML */
491
  attribs?: string;
492
}
493

494
/** Template view object for rendering templates */
495
interface TemplateView {
496
  /** Find function for querying doclets */
497
  find: (spec: Object) => Array<Doclet>;
498
  /** Create link to doclet */
499
  linkto: (longname: string, text?: string) => string;
500
  /** Resolve author links */
501
  resolveAuthorLinks: (text: string) => string;
502
  /** Create tutorial link */
503
  tutoriallink: (tutorial: string) => string;
504
  /** Make text HTML-safe */
505
  htmlsafe: (text: string) => string;
506
  /** Whether to output source files */
507
  outputSourceFiles: boolean;
508
  /** Generated navigation HTML */
509
  nav: string;
510
  /** Layout template file */
511
  layout: string;
512
  /** Render template with data */
513
  render: (templateName: string, data: Object) => string;
514
}
515
```
516

517
## Error Handling
518

519
Minami handles several error conditions during documentation generation:
520

521
- **Missing source files**: Logs errors when source files cannot be read for source view generation
522
- **Template rendering errors**: JSDoc's template engine handles template syntax errors
523
- **Invalid doclet data**: Gracefully handles missing or malformed doclet properties
524
- **File system errors**: Handles directory creation and file writing errors during output generation
525
- **Navigation typos**: Contains a typo bug in line 388 where `linkfoFn` should be `linktoFn`
526

527
## Usage Examples
528

529
### Basic JSDoc Integration
530

531
```bash
532
# Install minami as development dependency
533
npm install --save-dev minami
534

535
# Generate documentation with minami template
536
npx jsdoc src/ -t node_modules/minami -d docs/
537
```
538

539
### Advanced Configuration
540

541
```json
542
{
543
  "tags": {
544
    "allowUnknownTags": true,
545
    "dictionaries": ["jsdoc"]
546
  },
547
  "source": {
548
    "include": ["./src"],
549
    "includePattern": "\\.(js|jsx)$",
550
    "exclude": ["node_modules/"]
551
  },
552
  "plugins": ["plugins/markdown"],
553
  "templates": {
554
    "cleverLinks": false,
555
    "monospaceLinks": true,
556
    "useLongnameInNav": 3,
557
    "showInheritedInNav": true
558
  },
559
  "opts": {
560
    "destination": "./documentation/",
561
    "encoding": "utf8",
562
    "private": false,
563
    "recurse": true,
564
    "template": "./node_modules/minami"
565
  }
566
}
567
```
568

569
### Package.json Script Integration
570

571
```json
572
{
573
  "scripts": {
574
    "docs": "jsdoc --configure .jsdoc.json --verbose",
575
    "docs:watch": "nodemon --watch src --ext js --exec \"npm run docs\""
576
  }
577
}
578
```