or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

category-organization.mdcomponent-bundling.mdcomponent-documentation.mdcontent-loading.mdindex.mdtheme-engine.mdtypedef-import.mdtypescript-support.md
tile.json

category-organization.mddocs/

Category Organization

Hierarchical organization system that allows grouping documentation elements into categories and subcategories for better navigation.

Capabilities

Category Event Handlers

JSDoc event handlers for processing category tags and organizing documentation elements.

interface CategoryHandlers {
  /**
   * Processes doclets to handle @category and @subcategory tags
   * @param {Object} docletEvent - Doclet event containing category information
   */
  newDoclet(docletEvent: DocletEvent): void;
}

interface DocletEvent {
  doclet: {
    /** JSDoc tags array */
    tags?: TagInfo[];
    /** Assigned category name */
    category?: string;
    /** Assigned subcategory name */
    subCategory?: string;
  };
}

interface TagInfo {
  /** Tag name (category or subcategory) */
  title: string;
  /** Tag value */
  value: string;
}

Usage Patterns

Basic Category Assignment

Assign documentation elements to categories using the @category tag:

/**
 * User authentication utilities
 * @category Authentication
 */
class AuthService {
  /**
   * Authenticates user credentials
   * @param {string} username - User's username
   * @param {string} password - User's password
   * @returns {Promise<AuthResult>} Authentication result
   */
  async authenticate(username, password) {
    // Implementation
  }
}

/**
 * Password validation utility
 * @category Authentication
 */
function validatePassword(password) {
  // Implementation
}

/**
 * JWT token management
 * @category Authentication
 */
class TokenManager {
  // Implementation
}

Subcategory Organization

Use @subcategory tags to create hierarchical organization within categories:

/**
 * HTTP client for API requests
 * @category Networking
 * @subcategory HTTP
 */
class HttpClient {
  /**
   * Performs GET request
   * @param {string} url - Request URL
   * @returns {Promise<Response>} HTTP response
   */
  async get(url) {
    // Implementation
  }
}

/**
 * WebSocket connection manager
 * @category Networking
 * @subcategory WebSocket
 */
class WebSocketManager {
  /**
   * Establishes WebSocket connection
   * @param {string} url - WebSocket URL
   */
  connect(url) {
    // Implementation
  }
}

/**
 * FTP file transfer utility
 * @category Networking
 * @subcategory FTP
 */
class FtpClient {
  /**
   * Uploads file via FTP
   * @param {string} localPath - Local file path
   * @param {string} remotePath - Remote file path
   */
  upload(localPath, remotePath) {
    // Implementation
  }
}

Multi-level Category Structure

Create complex hierarchical structures with multiple categories and subcategories:

/**
 * Database connection pool
 * @category Data
 * @subcategory Database
 */
class ConnectionPool {
  // Implementation
}

/**
 * SQL query builder
 * @category Data
 * @subcategory Database
 */
class QueryBuilder {
  // Implementation
}

/**
 * Redis cache manager
 * @category Data
 * @subcategory Cache
 */
class RedisCache {
  // Implementation
}

/**
 * File system utilities
 * @category Data
 * @subcategory FileSystem
 */
class FileUtils {
  // Implementation
}

/**
 * CSV parser
 * @category Data
 * @subcategory Parsing
 */
class CsvParser {
  // Implementation
}

/**
 * JSON validator
 * @category Data
 * @subcategory Parsing
 */
class JsonValidator {
  // Implementation
}

Category-based Navigation Structure

The category plugin generates navigation that reflects the hierarchical organization:

Documentation
├── Authentication
│   ├── AuthService
│   ├── validatePassword
│   └── TokenManager
├── Networking
│   ├── HTTP
│   │   └── HttpClient
│   ├── WebSocket
│   │   └── WebSocketManager
│   └── FTP
│       └── FtpClient
└── Data
    ├── Database
    │   ├── ConnectionPool
    │   └── QueryBuilder
    ├── Cache
    │   └── RedisCache
    ├── FileSystem
    │   └── FileUtils
    └── Parsing
        ├── CsvParser
        └── JsonValidator

Mixed Organization

Elements without categories appear in the root scope, while categorized elements are organized hierarchically:

/**
 * Main application entry point
 * (No category - appears in root)
 */
class Application {
  // Implementation
}

/**
 * Global configuration manager
 * (No category - appears in root)
 */
const Config = {
  // Implementation
};

/**
 * User interface components
 * @category UI
 */
class Button {
  // Implementation
}

/**
 * Form input component  
 * @category UI
 * @subcategory Forms
 */
class TextInput {
  // Implementation
}

Configuration

Enable category organization in JSDoc configuration:

{
  "tags": {
    "allowUnknownTags": ["category", "subcategory"]
  },
  "plugins": [
    "node_modules/better-docs/category"
  ]
}

Alternatively, you can allow all unknown tags:

{
  "tags": {
    "allowUnknownTags": true
  },
  "plugins": [
    "node_modules/better-docs/category"
  ]
}

Best Practices

Category Naming

Use clear, descriptive category names that reflect the functional area:

// Good category names
/**
 * @category Authentication
 * @category DataAccess  
 * @category UserInterface
 * @category Networking
 * @category Utilities
 */

// Avoid vague names
/**
 * @category Stuff
 * @category Misc
 * @category Other
 */

Logical Grouping

Group related functionality together:

// Group all authentication-related code
/**
 * @category Authentication
 */

// Group all data access code
/**
 * @category DataAccess
 */

// Group UI components
/**
 * @category Components
 * @subcategory Forms
 */

Consistent Subcategory Usage

Use subcategories consistently within each category:

/**
 * @category Components
 * @subcategory Layout
 */
class Header { }

/**
 * @category Components  
 * @subcategory Layout
 */
class Footer { }

/**
 * @category Components
 * @subcategory Forms
 */
class FormInput { }

/**
 * @category Components
 * @subcategory Forms  
 */
class FormButton { }

Balance Organization Depth

Avoid over-categorization that makes navigation complex:

// Good balance
/**
 * @category Networking
 * @subcategory HTTP
 */

// Too deep - avoid this
/**
 * @category Networking
 * @subcategory HTTP
 * @sub-subcategory Requests
 * @sub-sub-subcategory GET
 */