or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcomment-tags.mdconfiguration.mdcore-generation.mdindex.mdoutput-generation.mdparsing.mdplugins.md
tile.json

output-generation.mddocs/

HTML Output Generation

Template processing and asset bundling for generating the final HTML documentation. Supports both multi-file and single-file output formats with customizable templates and styling.

Note: The Writer class is internal to ApiDoc and not part of the public API. This documentation is for reference and understanding the system architecture.

Writer Class

class Writer {
  constructor(api: ApiDocResult, app: App, cacheBustingQueryParam?: string);
  write(): Promise<string>;
  createOutputFiles(): Promise<string>;
  createSingleFile(): Promise<void>;
  getIndexContent(): string;
  runWebpack(outputPath: string): Promise<string>;
  findAsset(assetPath: string): string;
  writeJsonFile(dest: string, data: string): void;
  writeJSFile(dest: string, data: string): void;
  createDir(dir: string): void;
}

The Writer class handles generation of HTML documentation files and associated assets.

Constructor Parameters:

  • api (ApiDocResult): Parsed API data and project information
  • app (App): Application context with options and logger
  • cacheBustingQueryParam (string, optional): Query parameter for cache busting (default: v=${Date.now()})

Core Methods

write

write(): Promise<string>;

Main method to generate documentation files. Automatically chooses between single-file or multi-file output based on options.

Returns: Promise resolving to the output path

createOutputFiles

createOutputFiles(): Promise<string>;

Creates multi-file HTML output with separate assets directory.

Generated Structure:

output/
├── index.html
└── assets/
    ├── main.bundle.js
    ├── bootstrap.min.css
    ├── prism.css
    ├── main.css
    ├── api-data.json (optional)
    └── fonts/

Returns: Promise resolving to the assets directory path

createSingleFile

createSingleFile(): Promise<void>;

Creates a self-contained single HTML file with embedded CSS and JavaScript.

Generated File:

  • index.html - Complete documentation in a single file

getIndexContent

getIndexContent(): string;

Generates the main HTML content with template variable substitution.

Template Variables:

  • __API_NAME__: Project name or title
  • __API_DESCRIPTION__: Project description
  • __API_CACHE_BUSTING_QUERY_PARAM__: Cache busting parameter

Returns: Processed HTML content string

Asset Management

findAsset

findAsset(assetPath: string): string;

Locates assets from node_modules dependencies.

Parameters:

  • assetPath (string): Path relative to node_modules (e.g., 'bootstrap/dist/css/bootstrap.min.css')

Returns: Absolute path to the asset file

Asset Dependencies

The system automatically includes these assets:

CSS Files:

  • Bootstrap 3.4.1 (bootstrap/dist/css/bootstrap.min.css)
  • Prism.js syntax highlighting (prismjs/themes/prism-tomorrow.css)
  • Prism.js toolbar (prismjs/plugins/toolbar/prism-toolbar.css)
  • Prism.js diff highlight (prismjs/plugins/diff-highlight/prism-diff-highlight.css)
  • Custom main.css from template

JavaScript Files:

  • Main bundle (generated via Webpack)
  • jQuery, Bootstrap, Prism.js, and custom UI components

Fonts:

  • Glyphicons from Bootstrap template

Images:

  • Favicons and logos from template

Webpack Integration

runWebpack

runWebpack(outputPath: string): Promise<string>;

Runs Webpack to bundle JavaScript assets and inject API data.

Parameters:

  • outputPath (string): Directory where bundle should be created

Returns: Promise resolving to the output path

Webpack Configuration:

  • Mode: 'production' (default) or 'development' (with --debug)
  • Devtool: 'inline-source-map' (with --debug)
  • DefinePlugin: Injects API_DATA and API_PROJECT constants

File Writing Utilities

writeJsonFile

writeJsonFile(dest: string, data: string): void;

Writes JSON data to file with proper formatting.

writeJSFile

writeJSFile(dest: string, data: string): void;

Writes JavaScript files in different module formats based on options:

  • AMD format: define(data);
  • ES modules: export default data;
  • CommonJS: module.exports = data;

createDir

createDir(dir: string): void;

Creates directory and any necessary parent directories.

Usage Examples

Basic Multi-File Output

const Writer = require('apidoc/lib/writer');

const api = {
  data: JSON.stringify([/* API data */]),
  project: JSON.stringify({/* project info */})
};

const app = {
  options: {
    dest: './docs/',
    template: './template/',
    writeJson: true
  },
  log: console
};

const writer = new Writer(api, app);
writer.write().then(() => {
  console.log('Documentation generated successfully');
});

Single File Output

const Writer = require('apidoc/lib/writer');

const api = {
  data: JSON.stringify([/* API data */]),
  project: JSON.stringify({/* project info */})
};

const app = {
  options: {
    dest: './docs/',
    single: true,
    template: './template/'
  },
  log: console
};

const writer = new Writer(api, app);
writer.write().then(() => {
  console.log('Single-file documentation generated');
});

Dry Run Mode

const Writer = require('apidoc/lib/writer');

const api = {
  data: JSON.stringify([/* API data */]),
  project: JSON.stringify({/* project info */})
};

const app = {
  options: {
    dest: './docs/',
    dryRun: true
  },
  log: console
};

const writer = new Writer(api, app);
writer.write().then(() => {
  console.log('Dry run completed - no files created');
});

Custom Cache Busting

const Writer = require('apidoc/lib/writer');

const cacheBuster = `v=${process.env.BUILD_NUMBER || Date.now()}`;
const writer = new Writer(api, app, cacheBuster);

writer.write();

Template Customization

Template Structure

template/
├── index.html          # Main HTML template
├── src/
│   ├── css/
│   │   └── main.css    # Custom CSS styles
│   ├── webpack.config.js # Webpack configuration
│   └── *.js            # JavaScript source files
├── fonts/              # Font files
└── img/                # Image assets

Custom Template Usage

const Writer = require('apidoc/lib/writer');

const app = {
  options: {
    dest: './docs/',
    template: './custom-template/', // Custom template directory
    writeJson: true
  },
  log: console
};

const writer = new Writer(api, app);
writer.write();

Template Variables

The index.html template supports these placeholder variables:

<!DOCTYPE html>
<html>
<head>
    <title>__API_NAME__</title>
    <meta name="description" content="__API_DESCRIPTION__">
</head>
<body>
    <!-- Content will be injected here -->
    <script src="assets/main.bundle.js?__API_CACHE_BUSTING_QUERY_PARAM__"></script>
</body>
</html>

Output File Structure

Multi-File Output

docs/
├── index.html                    # Main documentation page
└── assets/
    ├── main.bundle.js           # JavaScript bundle
    ├── bootstrap.min.css        # Bootstrap CSS
    ├── bootstrap.min.css.map    # Bootstrap source map
    ├── prism.css               # Syntax highlighting CSS
    ├── prism-toolbar.css       # Prism toolbar CSS
    ├── prism-diff-highlight.css # Prism diff CSS
    ├── main.css                # Custom CSS
    ├── api-data.json           # API data (if writeJson: true)
    ├── *.png                   # Image assets
    ├── *.ico                   # Favicon files
    └── fonts/
        └── *.woff              # Font files

Single File Output

docs/
└── index.html                   # Self-contained documentation

Error Handling

Common Output Errors

  1. Permission Errors: Cannot write to destination directory
  2. Asset Errors: Cannot find or copy required assets
  3. Template Errors: Custom template files are missing or malformed
  4. Webpack Errors: JavaScript bundling fails

Error Handling Example

const Writer = require('apidoc/lib/writer');

const writer = new Writer(api, app);

writer.write()
  .then((outputPath) => {
    console.log(`Documentation written to: ${outputPath}`);
  })
  .catch((error) => {
    if (error.code === 'EACCES') {
      console.error('Permission denied: Cannot write to output directory');
    } else if (error.code === 'ENOENT') {
      console.error('Output directory or template not found');
    } else {
      console.error('Output generation failed:', error.message);
    }
    process.exit(1);
  });

Performance Considerations

Webpack Optimization

  • Production mode enables minification and optimization
  • Development mode (--debug) includes source maps for debugging
  • Asset caching via query parameters prevents browser cache issues

Large API Documentation

For APIs with many endpoints:

  • Consider using single-file output for deployment simplicity
  • Enable JSON output for programmatic access to API data
  • Use custom templates to optimize rendering performance

Build Integration

// Build script integration
const Writer = require('apidoc/lib/writer');

async function buildDocs(apiData, options) {
  const writer = new Writer(apiData, { 
    options: {
      ...options,
      template: path.join(__dirname, 'custom-template')
    },
    log: console 
  });
  
  try {
    const outputPath = await writer.write();
    console.log(`✓ Documentation built: ${outputPath}`);
    return outputPath;
  } catch (error) {
    console.error('✗ Documentation build failed:', error.message);
    throw error;
  }
}