Theme System

/**
 * The main theme class for the plugin that controls how TypeDoc models 
 * are mapped to files and templates for markdown generation
 */
class MarkdownTheme extends Theme {
  /** The router instance used for file organization */
  router: Router;
  
  /**
   * Creates a new markdown theme instance
   * @param renderer - The TypeDoc renderer instance
   */
  constructor(renderer: Renderer);
  
  /**
   * Renders a template and page model to a markdown string
   * @param page - The page event containing model and context
   * @returns Rendered markdown content
   */
  render(page: MarkdownPageEvent): string;
  
  /**
   * Gets navigation structure for the project
   * @param project - The TypeDoc project reflection
   * @returns Navigation item hierarchy
   */
  getNavigation(project: ProjectReflection): NavigationItem[];
  
  /**
   * Gets the render context for a specific page
   * @param page - The page event for a reflection
   * @returns Theme context with templates, partials, and helpers
   */
  getRenderContext(page: MarkdownPageEvent<Reflection>): MarkdownThemeContext;
  
  /**
   * Renders the main index template for projects
   * @param page - Page event for project reflection
   * @returns Rendered index markdown
   */
  indexTemplate(page: MarkdownPageEvent<ProjectReflection>): string;
  
  /**
   * Renders template for declaration reflections (classes, interfaces, etc.)
   * @param page - Page event for declaration reflection
   * @returns Rendered declaration markdown
   */
  reflectionTemplate(page: MarkdownPageEvent<DeclarationReflection>): string;
  
  /**
   * Renders template for document reflections (readme files, etc.)
   * @param page - Page event for document reflection
   * @returns Rendered document markdown
   */
  documentTemplate(page: MarkdownPageEvent<DocumentReflection>): string;
  
  /**
   * Renders hierarchy template showing class/interface inheritance
   * @param page - Page event for project reflection
   * @returns Rendered hierarchy markdown
   */
  hierarchyTemplate(page: MarkdownPageEvent<ProjectReflection>): string;
}

import { MarkdownTheme } from "typedoc-plugin-markdown";
import { Renderer } from "typedoc";

// Create custom theme
class CustomMarkdownTheme extends MarkdownTheme {
  constructor(renderer: Renderer) {
    super(renderer);
  }
  
  // Override rendering behavior
  render(page: MarkdownPageEvent): string {
    const context = this.getRenderContext(page);
    
    // Custom rendering logic
    let content = super.render(page);
    content = `<!-- Custom Header -->\n${content}`;
    
    return content;
  }
}

// Register custom theme
renderer.defineTheme('custom-markdown', CustomMarkdownTheme);

/**
 * The theme context class that provides context on the rendering of every page.
 * Contains templates, partials, helpers, and utility functions for markdown generation.
 */
class MarkdownThemeContext {
  /** The markdown router instance for URL generation */
  public router: Router;
  
  /** The theme instance */
  readonly theme: MarkdownTheme;
  
  /** The current page event being rendered */
  readonly page: MarkdownPageEvent<Reflection>;
  
  /** The options provided to the application */
  readonly options: Options;
  
  /** The templates namespace with main page templates */
  templates: any;
  
  /** The partials namespace with component partials */
  partials: any;
  
  /** The helpers namespace with utility functions */
  helpers: any;
  
  /** Hook into TypeDoc rendering system */
  hook: MarkdownRenderer['markdownHooks']['emit'];
  
  /**
   * Creates a new theme context instance
   * @param theme - The markdown theme instance
   * @param page - The current page event
   * @param options - TypeDoc options
   */
  constructor(
    theme: MarkdownTheme, 
    page: MarkdownPageEvent<Reflection>, 
    options: Options
  );
  
  /**
   * Gets package metadata for a specific package name
   * @param packageName - Name of the package
   * @returns Package metadata or undefined if not found
   */
  getPackageMetaData(packageName: string): PackageMetaData | undefined;
  
  /**
   * Returns the number of packages in the project (for packages mode)
   * @returns Number of packages
   */
  getPackagesCount(): number;
  
  /**
   * Returns a URL relative to the current page
   * @param url - The absolute URL to make relative
   * @returns Relative URL string
   */
  relativeURL(url: string): string;
  
  /**
   * Returns the relative URL of a given reflection
   * @param reflection - The reflection to get URL for
   * @returns Relative URL to the reflection
   */
  urlTo(reflection: Reflection): string;
}

// Using context in custom templates
function customTemplate(context: MarkdownThemeContext): string {
  const { page, options, helpers, partials } = context;
  
  // Use helpers for common operations
  const title = helpers.getReflectionTitle(page.model);
  const toc = partials.toc(page.model);
  
  // Access current page information
  const isIndex = page.pageKind === 'index';
  const packageCount = context.getPackagesCount();
  
  // Generate relative URLs
  const homeUrl = context.relativeURL('/');
  
  return `# ${title}
  
${toc}

[Back to Home](${homeUrl})
`;
}

/**
 * Builds navigation structure for the documentation
 */
class NavigationBuilder {
  /** Router instance for URL generation */
  router: Router;
  
  /** Theme instance */
  theme: MarkdownTheme;
  
  /** Project being documented */
  project: ProjectReflection;
  
  /**
   * Creates a new navigation builder
   * @param router - Router instance
   * @param theme - Theme instance  
   * @param project - Project instance
   */
  constructor(router: Router, theme: MarkdownTheme, project: ProjectReflection);
  
  /**
   * Gets the complete navigation structure for the project
   * @returns Hierarchical navigation items
   */
  getNavigation(): NavigationItem[];
}

/**
 * Returns bound template functions for the theme context
 * @param context - The markdown theme context
 * @returns Object containing bound template functions
 */
function resourceTemplates(context: MarkdownThemeContext): any;

/**
 * Returns bound partial functions for the theme context
 * @param context - The markdown theme context
 * @returns Object containing bound partial functions
 */
function resourcePartials(context: MarkdownThemeContext): any;

/**
 * Returns bound helper functions for the theme context
 * @param context - The markdown theme context
 * @returns Object containing bound helper functions
 */
function resourceHelpers(context: MarkdownThemeContext): any;

/**
 * Gets hierarchy roots from a project for rendering inheritance trees
 * @param project - The TypeDoc project
 * @returns Root reflections for hierarchy display
 */
function getHierarchyRoots(project: ProjectReflection): Reflection[];

/**
 * Checks if a section is a "None" section (ungrouped items)
 * @param section - The reflection group or category
 * @returns True if this is a "None" section
 */
function isNoneSection(section: ReflectionGroup | ReflectionCategory): boolean;

/**
 * Sorts sections with "None" section appearing first
 * @param sections - Array of sections to sort
 * @returns Sorted sections with None first
 */
function sortNoneSectionFirst<T extends ReflectionGroup | ReflectionCategory>(
  sections: T[]
): T[];

import { 
  MarkdownTheme, 
  MarkdownThemeContext,
  MarkdownPageEvent 
} from "typedoc-plugin-markdown";

class DocumentationTheme extends MarkdownTheme {
  constructor(renderer: Renderer) {
    super(renderer);
  }
  
  // Customize index page rendering
  indexTemplate(page: MarkdownPageEvent<ProjectReflection>): string {
    const context = this.getRenderContext(page);
    
    return `# ${page.model.name} Documentation

Welcome to the ${page.model.name} API documentation.

## Quick Navigation

${this.getNavigation(page.model).map(item => 
  `- [${item.title}](${item.path})`
).join('\n')}

## Overview

${context.helpers.getProjectDescription(page.model)}

---
*Generated with TypeDoc Plugin Markdown*
`;
  }
  
  // Add custom CSS classes to code blocks
  render(page: MarkdownPageEvent): string {
    let content = super.render(page);
    
    // Add custom styling
    content = content.replace(
      /```typescript/g, 
      '```typescript { .language-typescript .custom-theme }'
    );
    
    return content;
  }
}