Multiple output format generators for transforming parsed documentation comments into various human-readable formats including HTML, Markdown, JSON, and Remark AST.
Collection of output format generators that transform documentation comments into different presentation formats.
/**
* Output format functions for documentation generation
*/
interface Formats {
/** Generate HTML documentation with theming support */
html(comments: Comment[], config: HtmlConfig): Promise<string | void>;
/** Generate Markdown documentation */
md(comments: Comment[], config: MarkdownConfig): Promise<string>;
/** Generate Remark AST as JSON string */
remark(comments: Comment[], config: RemarkConfig): Promise<string>;
/** Generate JSON documentation data */
json(comments: Comment[]): Promise<string>;
}
interface HtmlConfig {
/** Theme name or path to custom theme */
theme?: string;
/** Project name for documentation */
name?: string;
/** Project version for documentation */
version?: string;
/** Enable GitHub source code linking */
github?: boolean;
/** Custom template variables */
[key: string]: any;
}
interface MarkdownConfig {
/** Generate table of contents */
markdownToc?: boolean;
/** Document only exported values */
documentExported?: boolean;
/** Additional markdown configuration */
[key: string]: any;
}
interface RemarkConfig {
/** Generate table of contents */
markdownToc?: boolean;
/** Document only exported values */
documentExported?: boolean;
/** Additional remark configuration */
[key: string]: any;
}Generates fully-featured HTML documentation with theme support, navigation, and interactive features.
/**
* Generate HTML documentation using themes
* @param comments - Parsed documentation comments
* @param config - HTML generation configuration
* @returns Promise resolving to HTML string or void (when output directory specified)
*/
function html(comments: Comment[], config: HtmlConfig): Promise<string | void>;Usage Examples:
import { build, formats } from "documentation";
// Generate HTML string (no output directory)
const comments = await build(['src/'], { access: ['public'] });
const htmlString = await formats.html(comments, {
theme: 'default',
name: 'My Project',
version: '1.0.0'
});
// Write HTML string to file
import fs from 'fs';
fs.writeFileSync('docs/index.html', htmlString);
// Generate HTML files to directory (writes files directly)
await formats.html(comments, {
theme: 'default',
name: 'My Project',
version: '2.1.0',
github: true,
output: './docs' // Files written directly to this directory
});The HTML format supports extensive customization:
Generates clean Markdown documentation suitable for README files, wikis, and documentation sites.
/**
* Generate Markdown documentation
* @param comments - Parsed documentation comments
* @param config - Markdown generation configuration
* @returns Promise resolving to markdown string
*/
function md(comments: Comment[], config: MarkdownConfig): Promise<string>;Usage Examples:
import { build, formats } from "documentation";
// Basic Markdown generation
const comments = await build(['index.js']);
const markdown = await formats.md(comments, {});
// Write to file
import fs from 'fs';
fs.writeFileSync('API.md', markdown);
// Markdown with table of contents
const markdown = await formats.md(comments, {
markdownToc: true
});
// Document only exported values
const markdown = await formats.md(comments, {
documentExported: true,
markdownToc: true
});Generates structured JSON data containing all parsed documentation information for programmatic use.
/**
* Generate JSON documentation data
* @param comments - Parsed documentation comments
* @returns Promise resolving to JSON string
*/
function json(comments: Comment[]): Promise<string>;Usage Examples:
import { build, formats } from "documentation";
// Generate JSON documentation
const comments = await build(['src/']);
const jsonData = await formats.json(comments);
// Parse and use the data
const documentation = JSON.parse(jsonData);
console.log(`Found ${documentation.length} documented items`);
// Write to file
import fs from 'fs';
fs.writeFileSync('api.json', jsonData);
// Use for custom processing
const parsedData = JSON.parse(jsonData);
const functions = parsedData.filter(item => item.kind === 'function');
const classes = parsedData.filter(item => item.kind === 'class');The JSON output contains complete documentation data:
[
{
"description": {
"type": "root",
"children": [...]
},
"tags": [...],
"loc": {
"start": { "line": 10, "column": 0 },
"end": { "line": 15, "column": 1 }
},
"context": {
"sortKey": "build",
"file": "src/index.js",
"code": "export const build = ...",
"loc": {...}
},
"name": "build",
"kind": "function",
"params": [...],
"returns": [...]
}
]Generates Remark-compatible Abstract Syntax Tree as JSON for advanced Markdown processing.
/**
* Generate Remark AST as JSON string
* @param comments - Parsed documentation comments
* @param config - Remark generation configuration
* @returns Promise resolving to JSON string of Remark AST
*/
function remark(comments: Comment[], config: RemarkConfig): Promise<string>;Usage Examples:
import { build, formats } from "documentation";
// Generate Remark AST
const comments = await build(['src/']);
const remarkAST = await formats.remark(comments, {
markdownToc: true
});
// Parse AST for custom processing
const ast = JSON.parse(remarkAST);
// Use with remark ecosystem
import { remark } from 'remark';
import remarkHtml from 'remark-html';
const processor = remark().use(remarkHtml);
const html = processor.stringify(ast);Choose the appropriate format based on your use case:
Combine formats for sophisticated documentation workflows:
import { build, formats } from "documentation";
const comments = await build(['src/']);
// Generate multiple formats
const [html, markdown, json] = await Promise.all([
formats.html(comments, { theme: 'default' }),
formats.md(comments, { markdownToc: true }),
formats.json(comments)
]);
// Custom processing
const data = JSON.parse(json);
const publicAPI = data.filter(item => item.access === 'public');
const customMarkdown = await formats.md(publicAPI, {});