Built-in Support for JSDoc Asset Path Resolution

[sashamilenkovic]

Feature Request: Built-in Support for JSDoc Asset Path Resolution

Summary

TypeDoc should provide built-in support for automatically resolving relative paths to assets referenced in JSDoc comments, similar to how JSDoc itself handles asset management. Currently, when migrating from JSDoc to TypeDoc, asset references break due to different relative path calculations between source files and the final documentation output.

Problem Statement

What JSDoc Supports

JSDoc's default template provides built-in asset management through staticFiles configuration:

// JSDoc configuration (jsdoc.conf.json)
{
  "templates": {
    "default": {
      "staticFiles": {
        "include": ["./config/jsdoc/template/static"]
      }
    }
  }
}

With this setup, JSDoc's documentation states:

"If your static files directory contains the file ./myproject/static/img/screen.png, you can display the image in your docs by using the HTML tag <img src="img/screen.png">."

This means JSDoc provides a mechanism where asset references in documentation comments work consistently, regardless of where the source file is located in the project structure.

Current Issues with TypeDoc

When using TypeDoc with projects that have existing JSDoc-style asset references, developers encounter several problems:

1. Asset Path Warnings: TypeDoc shows warnings for assets that can't be resolved from source file locations
2. Broken Documentation: Images and other assets don't display correctly in generated docs
3. Migration Friction: Moving from JSDoc to TypeDoc requires manually updating hundreds of asset paths
4. Maintenance Burden: Asset paths must be maintained for each source file's relative location

Example of the Problem

// In /src/models/components/Button.ts
/**
 * A reusable button component with various styles.
 *
 * <img src="img/components/button-example.png" width="400">
 * ^
 * This path works in JSDoc but fails in TypeDoc because:
 * - JSDoc resolves relative to the configured asset base directory
 * - TypeDoc tries to resolve relative to the source file location
 */
class Button {}

Current TypeDoc behavior:

• Looks for: /src/models/components/img/components/button-example.png (incorrect)
• Should look for: /config/jsdoc/template/static/img/components/button-example.png (correct)

Proposed Solution

Add built-in configuration options to TypeDoc that automatically transform asset paths in JSDoc comments to use correct relative paths based on a configured asset base directory.

Suggested Configuration API

// typedoc.config.mjs
{
  // Base directory where assets are actually located
  assetBasePath: 'config/jsdoc/template/static',

  // Optional: Only transform specific URL patterns (for precision)
  assetUrlPatterns: ['img/', 'media/', 'diagrams/'],

  // Optional: Customize which HTML attributes to search
  assetAttributes: ['src', 'href', 'data-src'],
}

Suggested Approach

1. Pattern Detection: Find asset references matching configured patterns in JSDoc comments
2. Path Calculation: Calculate correct relative path from each source file to the asset base directory
3. Automatic Transformation: Replace asset URLs with correctly calculated relative paths
4. TypeDoc Integration: Let TypeDoc's existing asset pipeline handle validation, copying, and optimization

Example Transformation

// Source: /src/models/deep/nested/MyClass.ts
/**
 * <img src="img/example.png">
 */

// TypeDoc automatically transforms to:
/**
 * <img src="../../../../config/jsdoc/template/static/img/example.png">
 */

JSDoc Compatibility Reference

This feature would provide TypeDoc compatibility with JSDoc's established asset handling approach, allowing seamless migration from JSDoc to TypeDoc without rewriting asset references.

Use Cases

1. JSDoc Migration

Projects migrating from JSDoc to TypeDoc can preserve existing asset references without manual updates.

2. Shared Asset Libraries

Organizations with centralized documentation assets can reference them consistently across projects.

3. Template-based Documentation

Projects using documentation templates with pre-existing asset structures.

4. Multi-format Documentation

Projects that generate both JSDoc and TypeDoc output can use the same source comments.

[Gerrit0]

The ask for a assetBasePath option is reasonable, and pretty easy to implement.

The following would have been a totally reasonable feature request, if you wrote all of that yourself, I'm sorry, but my visceral reaction to it was "what is this LLM slop", and I was very tempted to just flat ignore it as a waste of my time to read...

I have a project which uses JSDoc's staticFiles option and have hundreds of links in my docs which assume a base directory for asset links. It would be great if TypeDoc supported a assetBasePath option when resolving links in doc comments.

[sashamilenkovic]

@Gerrit0 Hello Gerrit! Guilty as charged. If you would like, I'd be happy to close this and reopen a feature request, written in my own words this time around. Let me know if you'd like for me to move forward with that. Apologies for the trouble!

[Gerrit0]

No need, I spent the time reading this already, so will just use this issue