tessl/npm-better-docs

JSDoc theme that provides TypeScript support, component documentation with live previews, and enhanced categorization features

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Content Loading

Name: tessl/npm-better-docs
Author: tessl

Dynamic content loading system that allows including external files and processed content into documentation.

Capabilities

Load Tag Definition

Defines the @load tag for JSDoc to enable external content inclusion.

/**
 * Defines the @load tag for JSDoc
 * @param {Object} dictionary - JSDoc tag dictionary for registering new tags
 */
function defineTags(dictionary: Object): void;

interface TagDefinition {
  /**
   * Called when @load tag is encountered during parsing
   * @param {Object} doclet - JSDoc doclet being processed
   * @param {Object} tag - The @load tag information
   */
  onTagged(doclet: Object, tag: Object): void;
}

Content Loading Function

Loads and processes content from external files with markdown parsing support.

/**
 * Loads and processes content from external files
 * @param {Object} loadTag - JSDoc load tag containing file path
 * @param {string} docletFilePath - Base path for resolving relative file paths
 * @returns {string} Processed content ready for inclusion in documentation
 */
function load(loadTag: Object, docletFilePath: string): string;

interface LoadTag {
  /** File path to load (relative to docletFilePath) */
  value: string;
}

Component Preview Processing

Processes loaded content to fill component preview placeholders.

/**
 * Processes content to fill component preview placeholders
 * @param {string} body - Raw content body
 * @param {Function} mdParser - Markdown parser function
 * @returns {string} Processed content with component previews
 */
function fillComponentPreview(body: string, mdParser: Function): string;

Usage Patterns

Basic File Loading

Load external markdown or text files into documentation:

/**
 * User Management Service
 * 
 * @load ./user-service-examples.md
 * 
 * This service provides comprehensive user management functionality.
 */
class UserService {
  /**
   * Creates a new user
   * @param {Object} userData - User data
   * @returns {Promise<User>} Created user
   */
  async createUser(userData) {
    // Implementation
  }
}

File: user-service-examples.md

## Usage Examples

### Creating a User

```javascript
const userService = new UserService();
const newUser = await userService.createUser({
  name: 'John Doe',
  email: 'john@example.com'
});

Finding Users

const users = await userService.findUsers({ active: true });

### Loading Component Examples

Load component examples and interactive previews:

```javascript
/**
 * Button Component
 * 
 * @component
 * @load ./button-examples.md
 */
const Button = ({ variant, children, onClick }) => {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
};

File: button-examples.md

## Button Examples

### Basic Usage

```javascript
<Button variant="primary">Click Me</Button>

With Event Handler

<Button variant="secondary" onClick={() => alert('Clicked!')}>
  Alert Button
</Button>

### Loading API Documentation

Load detailed API documentation from separate files:

```javascript
/**
 * Database Connection Manager
 * 
 * @load ./database-api.md
 * 
 * Manages database connections with pooling and failover support.
 */
class DatabaseManager {
  /**
   * Executes a query
   * @load ./query-examples.md
   */
  async query(sql, params) {
    // Implementation
  }
}

Loading Code Snippets

Load reusable code examples:

/**
 * HTTP Client Utility
 * 
 * @load ./http-client-usage.md
 */
class HttpClient {
  /**
   * Performs GET request
   * @param {string} url - Request URL
   * @returns {Promise<Response>} HTTP response
   * 
   * @load ./get-request-examples.md
   */
  async get(url) {
    // Implementation  
  }

  /**
   * Performs POST request
   * @param {string} url - Request URL
   * @param {Object} data - Request data
   * @returns {Promise<Response>} HTTP response
   * 
   * @load ./post-request-examples.md
   */
  async post(url, data) {
    // Implementation
  }
}

Content Merging

The @load tag content is merged with existing JSDoc comments:

/**
 * Authentication Service
 * 
 * Provides secure authentication and authorization functionality.
 * 
 * @load ./auth-examples.md
 * 
 * @see {@link TokenManager} for token management
 * @see {@link UserService} for user operations
 */
class AuthService {
  // Implementation
}

The loaded content is appended to the existing description, creating a comprehensive documentation block.

Relative Path Resolution

File paths in @load tags are resolved relative to the source file location:

project/
├── src/
│   ├── services/
│   │   ├── user.service.js     // Contains @load ./examples/user-examples.md
│   │   └── examples/
│   │       └── user-examples.md
│   └── components/
│       ├── button.component.js // Contains @load ../docs/button-docs.md
│       └── docs/
│           └── button-docs.md

Markdown Processing

Loaded content is processed through the JSDoc markdown parser, supporting:

Headers - Converted to appropriate HTML headings
Code blocks - Syntax highlighted code examples
Links - Converted to HTML links with JSDoc link resolution
Lists - Formatted as HTML lists
Tables - Converted to HTML tables
Inline code - Formatted with code styling

Configuration

Enable content loading in JSDoc configuration:

{
  "plugins": [
    "node_modules/better-docs/load"
  ]
}

No additional configuration is required - the @load tag is automatically available once the plugin is enabled.

File Organization Best Practices

Organized Documentation Structure

Keep documentation files organized alongside source code:

src/
├── components/
│   ├── button/
│   │   ├── Button.js
│   │   ├── Button.examples.md
│   │   └── Button.stories.md
│   └── modal/
│       ├── Modal.js
│       ├── Modal.examples.md
│       └── Modal.api.md
├── services/
│   ├── api/
│   │   ├── ApiService.js
│   │   └── api-examples.md
│   └── auth/
│       ├── AuthService.js
│       └── auth-examples.md
└── docs/
    ├── common-examples.md
    └── shared-patterns.md

Reusable Content

Create shared documentation files for common patterns:

/**
 * Base API Service
 * @load ../docs/common-api-patterns.md
 */
class BaseApiService {
  // Implementation
}

/**
 * User API Service  
 * @load ../docs/common-api-patterns.md
 * @load ./user-api-examples.md
 */
class UserApiService extends BaseApiService {
  // Implementation
}