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

Better-Docs

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

Better-docs is a comprehensive JSDoc3 theme that extends documentation capabilities for JavaScript and TypeScript projects. It provides advanced features including TypeScript support with automatic conversion of type aliases and interfaces to JSDoc format, a category plugin for organizing documentation into nested sidebar structures, and a component plugin that generates live previews for React and Vue components.

Package Information

Package Name: better-docs
Package Type: npm
Language: JavaScript with TypeScript support
Installation: npm install --save-dev better-docs

Core Imports

Better-docs is a JSDoc theme and its components are accessed through JSDoc configuration and plugin system:

// In jsdoc.json configuration
{
  "opts": {
    "template": "node_modules/better-docs"
  },
  "plugins": [
    "node_modules/better-docs/typescript",
    "node_modules/better-docs/category", 
    "node_modules/better-docs/component",
    "node_modules/better-docs/typedef-import",
    "node_modules/better-docs/load"
  ]
}

For programmatic access to utilities:

const bundler = require('better-docs/bundler');
const typeConverter = require('better-docs/typescript/type-converter');
const { parseReact, parseVue } = require('better-docs/component');
const { load } = require('better-docs/lib/load');
const { defineTags } = require('better-docs/load');

Basic Usage

As JSDoc Theme

Configure JSDoc to use better-docs theme:

{
  "opts": {
    "template": "better-docs",
    "destination": "docs/"
  },
  "templates": {
    "better-docs": {
      "name": "My Project Documentation",
      "logo": "images/logo.png"
    }
  }
}

With TypeScript Support

Enable TypeScript processing:

{
  "tags": {
    "allowUnknownTags": ["optional"]
  },
  "plugins": [
    "node_modules/better-docs/typescript"
  ],
  "source": {
    "includePattern": "\\.(jsx|js|ts|tsx)$"
  }
}

With Component Documentation

Enable React/Vue component documentation:

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

Then document components with @component tag:

/**
 * Button component with customizable styling
 * @component
 * @example
 * return <Button variant="primary">Click me</Button>
 */
const Button = ({ variant, children }) => {
  return <button className={`btn btn-${variant}`}>{children}</button>;
};

Architecture

Better-docs is built around several key components:

Theme System: Core JSDoc template engine that processes documentation data
Plugin Architecture: Modular plugins for TypeScript, categories, and components
Type Conversion Engine: Automatic TypeScript-to-JSDoc conversion system
Component Renderer: Live preview system for React and Vue components
Build System: Parcel-based bundling for component previews

Capabilities

JSDoc Theme Engine

Core JSDoc3 theme functionality that generates enhanced HTML documentation with advanced navigation, categorization, and styling.

/**
 * Main JSDoc publish function that generates documentation
 * @param {Object} taffyData - JSDoc data collection
 * @param {Object} opts - JSDoc options
 * @param {Object} tutorials - Tutorial data
 */
function publish(taffyData, opts, tutorials): void;

Theme Engine

TypeScript Support

Automatic conversion of TypeScript constructs to JSDoc-compatible documentation, including type aliases, interfaces, and class members.

/**
 * Converts TypeScript types to JSDoc format
 * @param {string} src - TypeScript source code
 * @param {string} filename - Source file name
 * @returns {string} JSDoc-compatible type definitions
 */
function typeConverter(src: string, filename?: string): string;

interface JSDocHandlers {
  beforeParse(e: ParseEvent): void;
  newDoclet(docletEvent: DocletEvent): void;
}

TypeScript Support

Component Documentation

Live preview system for React and Vue components with automatic prop extraction and interactive examples.

/**
 * Parses React component and extracts metadata
 * @param {string} filePath - Component file path
 * @param {Object} doclet - JSDoc doclet
 * @returns {ComponentMetadata} Component information
 */
function parseReact(filePath: string, doclet: Object): ComponentMetadata;

/**
 * Parses Vue component and extracts metadata
 * @param {string} filePath - Component file path  
 * @param {Object} doclet - JSDoc doclet
 * @returns {ComponentMetadata} Component information
 */
function parseVue(filePath: string, doclet: Object): ComponentMetadata;

interface ComponentMetadata {
  displayName: string;
  filePath: string;
  props: PropInfo[];
  slots?: SlotInfo[];
  type: 'react' | 'vue';
}

Component Documentation

Category Organization

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

interface CategoryHandlers {
  newDoclet(docletEvent: DocletEvent): void;
}

interface DocletEvent {
  doclet: {
    tags?: TagInfo[];
    category?: string;
    subCategory?: string;
  };
}

Category Organization

Content Loading

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

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

/**
 * Loads and processes content from external files
 * @param {Object} loadTag - JSDoc load tag
 * @param {string} docletFilePath - Base path for relative loading
 * @returns {string} Processed content
 */
function load(loadTag: Object, docletFilePath: string): string;

Content Loading

Component Bundling

Build system that creates interactive component previews using Parcel bundler with support for React and Vue components.

/**
 * Bundles React/Vue components for live preview
 * @param {ComponentInfo[]} Components - Array of component information
 * @param {string} out - Output directory
 * @param {Object} config - Build configuration
 */
function bundle(Components: ComponentInfo[], out: string, config: Object): void;

interface ComponentInfo {
  component: {
    displayName: string;
    filePath: string;
    type: 'react' | 'vue';
  };
}

Component Bundling

TypeDef Import Cleanup

Removes TypeScript-style import type declarations from source code before JSDoc processing to prevent parsing errors.

interface TypeDefImportHandlers {
  /**
   * Processes source code before JSDoc parsing to remove import type declarations
   * @param {Object} e - Parse event containing source code
   */
  beforeParse(e: ParseEvent): void;
}

TypeDef Import Plugin

Configuration

Better-docs supports extensive configuration through JSDoc configuration files:

interface BetterDocsConfig {
  name?: string;
  logo?: string;
  title?: string;
  css?: string;
  trackingCode?: string;
  hideGenerator?: boolean;
  navButtons?: boolean;
  landing?: string;
  navLinks?: NavLink[];
  component?: ComponentConfig;
}

interface ComponentConfig {
  wrapper?: string;
  entry?: string[];
}

interface NavLink {
  label: string;
  href: string;
}

Types

interface ParseEvent {
  filename: string;
  source: string;
  componentInfo?: ComponentInfo;
}

interface TagInfo {
  title: string;
  value: string;
}

interface PropInfo {
  name: string;
  description?: string;
  type: string;
  required: boolean;
  defaultValue?: string;
}

interface SlotInfo {
  name: string;
  description?: string;
}

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/better-docs@2.7.x
Publish Source: CLI
Badge