tessl/npm-dumi

Documentation generator for React component libraries with live demos, API tables, and theming support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Configuration

Name: tessl/npm-dumi
Author: tessl

Comprehensive configuration system for controlling documentation generation, theming, and build behavior through .dumirc.ts configuration files.

Capabilities

Define Configuration

Main configuration function for setting up dumi projects.

/**
 * Define dumi configuration with type safety and validation
 * @param config - Configuration object with dumi-specific options
 * @returns Validated configuration object
 */
function defineConfig(config: IDumiUserConfig): IDumiUserConfig;

interface IDumiUserConfig {
  resolve?: {
    docDirs?: (string | { type?: string; dir: string })[];
    atomDirs?: { type: string; subType?: string; dir: string }[];
    codeBlockMode?: 'active' | 'passive';
    entryFile?: string;
    forceKebabCaseRouting?: boolean;
  };
  themeConfig?: IThemeConfig;
  apiParser?: {
    unpkgHost?: string;
    resolveFilter?: (args: { 
      id: string; 
      type: 'COMPONENT' | 'FUNCTION' 
    }) => boolean;
  };
  locales?: ILocale[];
  extraRemarkPlugins?: (string | Function | [string | Function, object])[];
  extraRehypePlugins?: (string | Function | [string | Function, object])[];
  autoAlias?: boolean;
  [key: string]: any;
}

Usage:

// .dumirc.ts
import { defineConfig } from "dumi";

export default defineConfig({
  themeConfig: {
    name: "My Component Library",
    logo: "/logo.svg",
  },
  resolve: {
    atomDirs: [{ type: "component", dir: "src" }],
    docDirs: ["docs"],
  },
});

Resolve Configuration

Configure how dumi discovers and processes documentation files.

interface ResolveConfig {
  /** Documentation directories for general docs */
  docDirs?: (string | { type?: string; dir: string })[];
  /** Component/asset directories for API documentation */
  atomDirs?: { type: string; subType?: string; dir: string }[];
  /** Code block parsing mode */
  codeBlockMode?: 'active' | 'passive';
  /** Entry file for API parsing */
  entryFile?: string;
  /** Force kebab-case routing */
  forceKebabCaseRouting?: boolean;
}

Usage:

export default defineConfig({
  resolve: {
    // Multiple doc directories
    docDirs: ["docs", "guides", { type: "tutorial", dir: "tutorials" }],
    
    // Component directories with types
    atomDirs: [
      { type: "component", dir: "src/components" },
      { type: "hook", dir: "src/hooks" },
    ],
    
    // Passive code block mode - requires explicit | demo
    codeBlockMode: "passive",
    
    // Entry file for API resolution
    entryFile: "./src/index.ts",
    
    // Use exact file names for routes
    forceKebabCaseRouting: false,
  },
});

Theme Configuration

Configure the visual appearance and behavior of the documentation site.

interface IThemeConfig {
  /** Site name displayed in header */
  name?: string;
  /** Logo image URL or false to disable */
  logo?: string | false;
  /** Navigation configuration */
  nav?: IUserNavValue | NavWithMode<IUserNavValue>;
  /** Sidebar configuration per route */
  sidebar?: Record<string, ISidebarGroup[]>;
  /** Footer content or false to disable */
  footer?: string | false;
  /** Show line numbers in code blocks */
  showLineNum?: boolean;
  /** Color scheme preferences */
  prefersColor: {
    default: 'light' | 'dark' | 'auto';
    switch: boolean;
  };
  /** Progress bar during navigation */
  nprogress?: boolean;
  /** Social media links */
  socialLinks?: {
    [key in SocialTypes]?: string;
  };
  /** Edit page link configuration */
  editLink?: boolean | string;
  /** Source code link configuration */
  sourceLink?: boolean | string;
  /** Show last updated timestamp */
  lastUpdated?: boolean;
}

Usage:

export default defineConfig({
  themeConfig: {
    name: "Design System",
    logo: "https://example.com/logo.png",
    footer: "Copyright © 2023 My Company",
    
    // Color scheme
    prefersColor: {
      default: "auto",
      switch: true,
    },
    
    // Social links
    socialLinks: {
      github: "https://github.com/user/repo",
      twitter: "https://twitter.com/user",
    },
    
    // Custom navigation
    nav: [
      { title: "Guide", link: "/guide" },
      { title: "Components", link: "/components" },
      { title: "API", link: "/api" },
    ],
    
    // Enable source and edit links
    editLink: true,
    sourceLink: true,
    lastUpdated: true,
  },
});

API Parser Configuration

Configure automatic API documentation generation from TypeScript/JavaScript code.

interface ApiParserConfig {
  /** Custom unpkg host for dependency resolution */
  unpkgHost?: string;
  /** Filter function to skip certain components/functions */
  resolveFilter?: (args: { 
    id: string; 
    type: 'COMPONENT' | 'FUNCTION' 
  }) => boolean;
}

Usage:

export default defineConfig({
  apiParser: {
    // Custom unpkg mirror for faster dependency resolution
    unpkgHost: "https://cdn.jsdelivr.net/npm",
    
    // Skip large or problematic components
    resolveFilter: ({ id, type }) => {
      // Skip internal components
      if (id.startsWith("_")) return false;
      
      // Skip specific large components that cause performance issues
      if (id === "ComplexDataGrid") return false;
      
      return true;
    },
  },
});

Localization Configuration

Configure multi-language support for documentation sites.

interface ILocale {
  /** Locale identifier */
  id: string;
  /** Display name for the locale */
  name: string;
  /** Base locale (for suffix-based routing) */
  base?: string;
  /** Suffix for URL routing */
  suffix?: string;
}

type ILocalesConfig = ILocale[];

Usage:

export default defineConfig({
  // Suffix-based locales (default English, Chinese with /zh suffix)
  locales: [
    { id: "en", name: "English" },
    { id: "zh", name: "中文", suffix: "zh" },
  ],
  
  // Or base-based locales (English at /en, Chinese at /zh)
  locales: [
    { id: "en", name: "English", base: "en" },
    { id: "zh", name: "中文", base: "zh" },
  ],
});

Plugin Configuration

Configure additional remark and rehype plugins for markdown processing.

interface PluginConfig {
  /** Additional remark plugins for markdown parsing */
  extraRemarkPlugins?: (string | Function | [string | Function, object])[];
  /** Additional rehype plugins for HTML generation */
  extraRehypePlugins?: (string | Function | [string | Function, object])[];
}

Usage:

export default defineConfig({
  extraRemarkPlugins: [
    // Plugin without options
    "remark-custom-plugin",
    
    // Plugin with options
    ["remark-highlight", { theme: "github" }],
    
    // Custom function plugin
    () => (tree) => {
      // Custom markdown processing
    },
  ],
  
  extraRehypePlugins: [
    ["rehype-external-links", { target: "_blank" }],
  ],
});

Additional Options

Other configuration options inherited from Umi framework.

interface AdditionalConfig {
  /** Auto-generate import aliases */
  autoAlias?: boolean;
  /** Output directory for built files */
  outputPath?: string;
  /** Public path for assets */
  publicPath?: string;
  /** HTML template configuration */
  html?: {
    title?: string;
    favicon?: string;
    meta?: Record<string, string>;
  };
  /** Build target environment */
  targets?: Record<string, any>;
  /** Server-side rendering configuration */
  ssr?: boolean | object;
}

Usage:

export default defineConfig({
  // Disable auto-alias generation
  autoAlias: false,
  
  // Custom output directory
  outputPath: "dist-docs",
  
  // CDN public path
  publicPath: "https://cdn.example.com/",
  
  // HTML configuration
  html: {
    title: "My Docs",
    favicon: "/favicon.ico",
    meta: {
      description: "Component library documentation",
      keywords: "react,components,design-system",
    },
  },
  
  // Enable SSR for better SEO
  ssr: true,
});

Configuration Examples

Basic Component Library

// .dumirc.ts
import { defineConfig } from "dumi";

export default defineConfig({
  themeConfig: {
    name: "UI Components",
    logo: "/logo.svg",
    footer: "MIT Licensed",
    socialLinks: {
      github: "https://github.com/user/ui-lib",
    },
  },
  resolve: {
    atomDirs: [{ type: "component", dir: "src" }],
  },
  apiParser: {},
});

Multi-language Documentation

// .dumirc.ts
import { defineConfig } from "dumi";

export default defineConfig({
  locales: [
    { id: "en", name: "English" },
    { id: "zh", name: "中文", suffix: "zh" },
  ],
  themeConfig: {
    name: "Design System",
    prefersColor: { default: "auto", switch: true },
  },
});

Advanced Configuration

// .dumirc.ts
import { defineConfig } from "dumi";

export default defineConfig({
  resolve: {
    docDirs: ["docs", "guides"],
    atomDirs: [
      { type: "component", dir: "src/components" },
      { type: "hook", dir: "src/hooks" },
      { type: "util", dir: "src/utils" },
    ],
    entryFile: "./src/index.ts",
  },
  
  apiParser: {
    resolveFilter: ({ id }) => !id.startsWith("_"),
  },
  
  themeConfig: {
    name: "Advanced UI",
    nav: [
      { title: "Guide", link: "/guide" },
      { title: "Components", link: "/components" },
      { title: "Hooks", link: "/hooks" },
      { title: "Utils", link: "/utils" },
    ],
    socialLinks: {
      github: "https://github.com/user/repo",
      twitter: "https://twitter.com/user",
    },
  },
  
  extraRemarkPlugins: [
    ["remark-toc", { heading: "Contents" }],
  ],
  
  ssr: { builder: "webpack" },
});

Install with Tessl CLI