Output and Rendering

/**
 * Main renderer coordinates output generation from reflections to various formats
 */
class Renderer extends AbstractComponent<Application, RendererEvents> {
  /** Application instance */
  readonly application: Application;
  /** Currently active theme */
  theme?: Theme;
  
  /**
   * Render project to output directory
   * @param project - Project reflection to render
   * @param outputDirectory - Target output directory
   */
  render(project: ProjectReflection, outputDirectory: string): Promise<void>;
  
  /**
   * Render individual document/page
   * @param page - Page event containing reflection data
   * @returns Rendered HTML content
   */
  renderDocument(page: PageEvent<Reflection>): string;
  
  /**
   * Get template for rendering specific reflection type
   * @param reflection - Reflection to get template for
   * @returns Template function
   */
  getTemplate(reflection: Reflection): RenderTemplate<PageEvent<Reflection>>;
  
  /**
   * Add template for specific reflection type
   * @param name - Template name
   * @param template - Template function
   */
  addTemplate(name: string, template: RenderTemplate<PageEvent<Reflection>>): void;
  
  /**
   * Remove template
   * @param name - Template name to remove
   */
  removeTemplate(name: string): void;
}

import { Application, Renderer } from "typedoc";

const app = await Application.bootstrap({
  entryPoints: ["src/index.ts"],
  out: "docs",
  theme: "default",
});

const project = await app.convert();
if (project) {
  // Render using the application's renderer
  await app.renderer.render(project, "docs");
  
  // Custom rendering with event handling
  app.renderer.on("beginPage", (page) => {
    console.log(`Rendering page: ${page.url}`);
  });
  
  app.renderer.on("endPage", (page) => {
    console.log(`Completed page: ${page.url}`);
  });
}

/**
 * Base theme class for rendering documentation
 */
abstract class Theme {
  /** Renderer instance */
  readonly renderer: Renderer;
  
  /**
   * Render a page using the theme
   * @param page - Page event with reflection data
   * @param template - Template function to use
   * @returns Rendered HTML content
   */
  abstract render(
    page: PageEvent<Reflection>, 
    template: RenderTemplate<PageEvent<Reflection>>
  ): string;
  
  /**
   * Get URL mappings for all pages
   * @param project - Project reflection
   * @returns Array of URL mappings
   */
  abstract getUrls(project: ProjectReflection): UrlMapping[];
  
  /**
   * Get navigation structure  
   * @param project - Project reflection
   * @returns Navigation element tree
   */
  abstract getNavigation(project: ProjectReflection): NavigationElement;
  
  /**
   * Get reflection URL
   * @param reflection - Reflection to get URL for
   * @returns URL string
   */
  getUrl(reflection: Reflection): string | undefined;
  
  /**
   * Get mapping between reflection and URL
   * @param reflection - Reflection to map
   * @returns URL mapping or undefined
   */
  getMapping(reflection: Reflection): UrlMapping | undefined;
}

/**
 * Default HTML theme implementation
 */
class DefaultTheme extends Theme {
  /** Theme context for rendering */
  context: DefaultThemeRenderContext;
  
  render(
    page: PageEvent<Reflection>, 
    template: RenderTemplate<PageEvent<Reflection>>
  ): string;
  
  getUrls(project: ProjectReflection): UrlMapping[];
  
  getNavigation(project: ProjectReflection): NavigationElement;
  
  /**
   * Get render context for theme
   * @param page - Page being rendered
   * @returns Render context
   */
  getRenderContext(page: PageEvent<Reflection>): DefaultThemeRenderContext;
}

import { DefaultTheme, Theme } from "typedoc";

// Create custom theme extending default
class CustomTheme extends DefaultTheme {
  render(page: PageEvent<Reflection>, template: RenderTemplate<PageEvent<Reflection>>): string {
    // Add custom header/footer
    const content = super.render(page, template);
    return `
      <div class="custom-header">Custom Documentation</div>
      ${content}
      <div class="custom-footer">© 2024 My Company</div>
    `;
  }
  
  getUrls(project: ProjectReflection): UrlMapping[] {
    const urls = super.getUrls(project);
    
    // Add custom pages
    urls.push({
      url: "custom-page.html",
      template: this.customPageTemplate,
      model: { title: "Custom Page", content: "Custom content" }
    });
    
    return urls;
  }
  
  private customPageTemplate = (page: PageEvent<any>) => {
    return `<h1>${page.model.title}</h1><p>${page.model.content}</p>`;
  };
}

// Register custom theme
app.renderer.theme = new CustomTheme(app.renderer);

/**
 * Base router interface for URL generation
 */
interface Router {
  /**
   * Get URL for reflection
   * @param reflection - Reflection to get URL for
   * @returns URL string or undefined
   */
  getUrl(reflection: Reflection): string | undefined;
  
  /**
   * Get all URL mappings
   * @param project - Project reflection
   * @returns Array of URL mappings
   */
  getUrls(project: ProjectReflection): UrlMapping[];
}

/**
 * Base router implementation
 */
class BaseRouter implements Router {
  /** Application instance */
  readonly application: Application;
  
  getUrl(reflection: Reflection): string | undefined;
  getUrls(project: ProjectReflection): UrlMapping[];
  
  /**
   * Build URL mapping for reflection
   * @param reflection - Reflection to map
   * @param template - Template to use
   * @returns URL mapping
   */
  buildUrlMapping(
    reflection: Reflection, 
    template: RenderTemplate<PageEvent<Reflection>>
  ): UrlMapping;
}

/**
 * Router that organizes output by reflection kind
 */
class KindRouter extends BaseRouter {
  /** Generate URLs with kind-based prefixes */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Router that creates directories by reflection kind
 */
class KindDirRouter extends BaseRouter {
  /** Generate URLs with kind-based directory structure */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Router that organizes by category
 */
class CategoryRouter extends BaseRouter {
  /** Generate URLs with category-based organization */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Router that organizes by group
 */
class GroupRouter extends BaseRouter {
  /** Generate URLs with group-based organization */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Router that uses project structure for URLs
 */
class StructureRouter extends BaseRouter {
  /** Generate URLs following source structure */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Router that creates directories following project structure
 */
class StructureDirRouter extends BaseRouter {
  /** Generate URLs with directory structure matching source */
  getUrl(reflection: Reflection): string | undefined;
}

/**
 * Event fired for each page being rendered
 */
class PageEvent<Model = Reflection> extends Event {
  /** URL for this page */
  url: string;
  /** Data model for the page */
  model: Model;
  /** Page template */
  template: RenderTemplate<PageEvent<Model>>;
  /** Project being rendered */
  project: ProjectReflection;
  /** Rendered page contents */
  contents?: string;
  /** Page filename */
  filename: string;
  
  /**
   * Create page event
   * @param name - Page name
   * @param model - Page data model
   * @param url - Page URL
   * @param template - Rendering template
   */
  constructor(
    name: string,
    model: Model,
    url: string, 
    template: RenderTemplate<PageEvent<Model>>
  );
}

/**
 * Types of pages that can be generated
 */
enum PageKind {
  Document = "document",
  Module = "module", 
  Namespace = "namespace",
  Class = "class",
  Interface = "interface",
  Enum = "enum",
  Function = "function",
  Variable = "variable",
  TypeAlias = "typealias",
  Index = "index",
  Hierarchy = "hierarchy",
  Search = "search",
}

/**
 * Page definition for routing
 */
interface PageDefinition {
  /** Page kind */
  kind: PageKind;
  /** URL pattern */
  url: string;
  /** Template function */
  template: RenderTemplate<PageEvent<Reflection>>;
  /** Page title pattern */
  title?: string;
}

/**
 * Router target for URL mapping
 */
interface RouterTarget {
  /** Target reflection */
  reflection: Reflection;
  /** Target URL */
  url: string;
  /** Page kind */
  kind: PageKind;
}

/**
 * URL mapping result
 */
interface UrlMapping {
  /** Target URL */
  url: string;
  /** Page template */
  template: RenderTemplate<PageEvent<any>>;
  /** Page model/data */
  model: any;
}

/**
 * Navigation element in the documentation structure
 */
interface NavigationElement {
  /** Element title */
  title: string;
  /** Element URL */
  url?: string;
  /** Child navigation elements */
  children?: NavigationElement[];
  /** CSS classes for styling */
  cssClasses?: string;
  /** Whether element is expanded */
  expanded?: boolean;
  /** Associated reflection */
  reflection?: Reflection;
}

/**
 * Page heading structure
 */
interface PageHeading {
  /** Heading level (1-6) */
  level: number;
  /** Heading text */
  title: string;
  /** Heading anchor/ID */
  anchor: string;
  /** CSS classes */
  cssClasses?: string;
}

/**
 * Template function type for rendering pages
 */
type RenderTemplate<T extends PageEvent<any>> = (data: T) => string;

/**
 * Icons interface for theme customization
 */
interface Icons {
  /** Icon for modules */
  module: string;
  /** Icon for classes */
  class: string;
  /** Icon for interfaces */
  interface: string;
  /** Icon for enums */
  enum: string;
  /** Icon for functions */
  function: string;
  /** Icon for variables */
  variable: string;
  /** Icon for type aliases */
  typeAlias: string;
  /** Icon for properties */
  property: string;
  /** Icon for methods */
  method: string;
  /** Icon for constructors */
  constructor: string;
  /** Icon for accessors */
  accessor: string;
  /** Icon for parameters */
  parameter: string;
  /** Search icon */
  search: string;
  /** Menu icon */
  menu: string;
  /** Chevron icons for navigation */
  chevronDown: string;
  chevronSmall: string;
}

/**
 * Default theme render context
 */
class DefaultThemeRenderContext {
  /** Icon set */
  icons: Icons;
  /** Hook functions for customization */
  hooks: RendererHooks;
  
  /**
   * Render reflection as HTML
   * @param reflection - Reflection to render
   * @returns HTML string
   */
  reflectionTemplate(reflection: Reflection): string;
  
  /**
   * Render navigation
   * @param navigation - Navigation structure
   * @returns HTML string
   */
  navigationTemplate(navigation: NavigationElement): string;
  
  /**
   * Render page header
   * @param page - Page event
   * @returns HTML string
   */
  headerTemplate(page: PageEvent<Reflection>): string;
  
  /**
   * Render page footer
   * @param page - Page event  
   * @returns HTML string
   */
  footerTemplate(page: PageEvent<Reflection>): string;
}

/**
 * URL slug generator with collision handling
 */
class Slugger {
  /**
   * Generate URL slug from text
   * @param text - Text to convert to slug
   * @returns URL-safe slug
   */
  slug(text: string): string;
  
  /**
   * Reset slug generator state
   */
  reset(): void;
  
  /**
   * Check if slug already exists
   * @param slug - Slug to check
   * @returns True if slug exists
   */
  hasSlug(slug: string): boolean;
}

/**
 * Output format management
 */
class Outputs {
  /** Application instance */
  readonly application: Application;
  
  /**
   * Add output format
   * @param name - Output format name
   * @param output - Output function
   */
  addOutput(
    name: string,
    output: (path: string, project: ProjectReflection) => Promise<void>
  ): void;
  
  /**
   * Set default output format name
   * @param name - Default output name
   */
  setDefaultOutputName(name: string): void;
  
  /**
   * Get output specifications from configuration
   * @returns Array of output specifications
   */
  getOutputSpecs(): OutputSpecification[];
  
  /**
   * Generate all configured outputs
   * @param project - Project to output
   * @param logger - Logger for messages
   */
  async generate(project: ProjectReflection, logger: Logger): Promise<void>;
}

/**
 * Output specification
 */
interface OutputSpecification {
  /** Output name/format */
  name: string;
  /** Output path */
  path: string;
  /** Format-specific options */
  options?: Partial<TypeDocOptions>;
}

/**
 * Events fired during rendering
 */
interface RendererEvents {
  /** Begin rendering process */
  BEGIN: [RendererEvent];
  /** End rendering process */
  END: [RendererEvent];
  /** Begin rendering page */
  BEGIN_PAGE: [PageEvent<Reflection>];
  /** End rendering page */
  END_PAGE: [PageEvent<Reflection>];
  /** Markdown content processing */
  MARK_DOWN: [MarkdownEvent];
  /** Index generation */
  INDEX: [IndexEvent];
}

/**
 * Renderer hooks for customization
 */
interface RendererHooks {
  /** Custom head content injection */
  head: (context: DefaultThemeRenderContext) => string;
  /** Custom body content injection */
  body: (context: DefaultThemeRenderContext) => string;
  /** Custom sidebar content */
  sidebar: (context: DefaultThemeRenderContext) => string;
}

/**
 * Base renderer event
 */
class RendererEvent extends Event {
  /** Project being rendered */
  readonly project: ProjectReflection;
  /** Output directory */
  readonly outputDirectory: string;
  /** URL mappings */
  readonly urls: UrlMapping[];
}

/**
 * Markdown processing event
 */
class MarkdownEvent extends Event {
  /** Original markdown content */
  readonly parsedText: string;
  /** Processed markdown content */
  outputText: string;
  /** Source reflection */
  readonly reflection?: Reflection;
}

/**
 * Index generation event
 */
class IndexEvent extends Event {
  /** Search index data */
  readonly searchResults: any[];
  /** Index file content */
  indexContent: string;
}

import { Application, RendererEvents } from "typedoc";

const app = await Application.bootstrap();

// Customize rendering process
app.renderer.on("beginPage", (page) => {
  console.log(`Rendering: ${page.url}`);
  
  // Add custom data to page
  if (page.model.kind === ReflectionKind.Class) {
    page.model.customData = "This is a class";
  }
});

app.renderer.on("markDown", (event) => {
  // Process markdown content
  event.outputText = event.parsedText.replace(
    /TODO:/g,
    '<span class="todo">TODO:</span>'
  );
});

app.renderer.on("endPage", (page) => {
  // Post-process rendered content
  if (page.contents) {
    page.contents = page.contents.replace(
      /<h1>/g,
      '<h1 class="custom-heading">'
    );
  }
});