Core JSDoc3 theme functionality that generates enhanced HTML documentation with advanced navigation, categorization, and styling.
The primary entry point for JSDoc theme processing that transforms JSDoc data into HTML documentation.
/**
* Main JSDoc publish function that generates documentation
* @param {Object} taffyData - JSDoc data collection containing all documented elements
* @param {Object} opts - JSDoc configuration options including template settings
* @param {Object} tutorials - Tutorial data for generating tutorial pages
*/
function publish(taffyData: Object, opts: Object, tutorials: Object): void;Usage Example:
// This function is called automatically by JSDoc when using better-docs theme
// Configure in jsdoc.json:
{
"opts": {
"template": "better-docs"
}
}Creates hierarchical navigation structure with category support and enhanced sidebar generation.
/**
* Creates the navigation sidebar with category support
* @param {Object} members - Categorized documentation members
* @param {string[]|null} navTypes - Types to include in navigation
* @param {Object} betterDocs - Better-docs configuration
* @returns {string} Generated navigation HTML
*/
function buildNav(members: Object, navTypes?: string[], betterDocs?: Object): string;
/**
* Builds navigation for a specific group with category support
* @param {Object} members - Group members to include
* @param {string} title - Group title
* @returns {string} Generated group navigation HTML
*/
function buildGroupNav(members: Object, title?: string): string;
/**
* Builds member navigation with subcategory support
* @param {Object[]} items - Items to include in navigation
* @param {string} itemHeading - Heading for the item group
* @param {Object} itemsSeen - Tracking object for seen items
* @param {Function} linktoFn - Link generation function
* @returns {string} Generated member navigation HTML
*/
function buildMemberNav(items: Object[], itemHeading: string, itemsSeen: Object, linktoFn: Function): string;Generates individual documentation pages for classes, modules, and other documented elements.
/**
* Generates HTML documentation page
* @param {string} title - Page title
* @param {string} subtitle - Page subtitle
* @param {Object[]} docs - Documentation elements for the page
* @param {string} filename - Output filename
* @param {boolean} resolveLinks - Whether to resolve JSDoc links
*/
function generate(title: string, subtitle: string, docs: Object[], filename: string, resolveLinks?: boolean): void;
/**
* Generates source file documentation pages
* @param {Object} sourceFiles - Source file information
* @param {string} encoding - File encoding (default: utf8)
*/
function generateSourceFiles(sourceFiles: Object, encoding?: string): void;Processes function and method signatures for enhanced display with type information.
/**
* Determines if a doclet needs a signature
* @param {Object} doclet - JSDoc doclet
* @returns {boolean} Whether signature is needed
*/
function needsSignature(doclet: Object): boolean;
/**
* Adds parameter information to function signature
* @param {Object} f - Function doclet
*/
function addSignatureParams(f: Object): void;
/**
* Adds return type information to function signature
* @param {Object} f - Function doclet
*/
function addSignatureReturns(f: Object): void;
/**
* Adds type information to signatures
* @param {Object} f - Function doclet
*/
function addSignatureTypes(f: Object): void;
/**
* Adds attribute information to doclets
* @param {Object} f - Function doclet
*/
function addAttribs(f: Object): void;Handles module exports and symbol attachment for proper documentation organization.
/**
* Attaches classes or functions to module doclets
* @param {Object[]} doclets - Array of class and function doclets
* @param {Object[]} modules - Array of module doclets
*/
function attachModuleSymbols(doclets: Object[], modules: Object[]): void;Helper functions for processing and formatting documentation elements.
/**
* Finds doclets matching specification
* @param {Object} spec - Search specification
* @returns {Object[]} Matching doclets
*/
function find(spec: Object): Object[];
/**
* Creates tutorial links
* @param {string} tutorial - Tutorial identifier
* @returns {string} Tutorial link HTML
*/
function tutoriallink(tutorial: string): string;
/**
* Gets ancestor links for a doclet
* @param {Object} doclet - JSDoc doclet
* @returns {string} Ancestor links HTML
*/
function getAncestorLinks(doclet: Object): string;
/**
* Converts hash links to proper HTML links
* @param {Object} doclet - JSDoc doclet
* @param {string} hash - Hash string to convert
* @returns {string} HTML link
*/
function hashToLink(doclet: Object, hash: string): string;
/**
* Gets path from doclet metadata
* @param {Object} doclet - JSDoc doclet
* @returns {string|null} File path
*/
function getPathFromDoclet(doclet: Object): string | null;The theme engine supports extensive configuration through JSDoc configuration files:
interface TemplateConfig {
/** Default JSDoc template configuration */
default?: {
layoutFile?: string;
staticFiles?: {
include?: string[];
paths?: string[];
};
outputSourceFiles?: boolean;
useLongnameInNav?: boolean;
};
/** Better-docs specific configuration */
"better-docs"?: BetterDocsConfig;
}
interface BetterDocsConfig {
/** Documentation site name */
name?: string;
/** Logo file path */
logo?: string;
/** HTML page title */
title?: string;
/** Custom CSS file */
css?: string;
/** Analytics tracking code */
trackingCode?: string;
/** Hide JSDoc generator info */
hideGenerator?: boolean;
/** Show navigation buttons */
navButtons?: boolean;
/** Custom landing page file */
landing?: string;
/** Navigation links */
navLinks?: Array<{
label: string;
href: string;
}>;
}Configuration Example:
{
"templates": {
"default": {
"outputSourceFiles": true,
"staticFiles": {
"include": ["./assets"]
}
},
"better-docs": {
"name": "My API Documentation",
"logo": "images/logo.png",
"title": "API Docs",
"navLinks": [
{
"label": "GitHub",
"href": "https://github.com/user/repo"
}
]
}
}
}