Add table of contents rendering

Resolves #1478

Author: Gerrit0

.config/typedoc.json

@@ -36,6 +36,6 @@
         "Enumerations": 2.0,
         "Type Aliases": 2.0
     },
-    "searchInComments": true,
+    "includeVersion": true,
     "logLevel": "Verbose"
 }

CHANGELOG.md

@@ -34,24 +34,26 @@
 -   Removed `Renderer.addExternalSymbolResolver`, use `Converter.addExternalSymbolResolver` instead.
 -   Removed `CallbackLogger`.
 -   Removed `SerializeEventData` from serialization events.
--   A `PageEvent` is no longer passed to `getRenderContext` by the default theme.
+-   A `PageEvent` is now required for `getRenderContext`. If caching the context object, `page` must be updated when `getRenderContext` is called.
+-   `PageEvent` no longer includes the `template` property. The `Theme.render` method is now expected to take the template to render the page with as its second argument.
 -   Removed `secondaryNavigation` member on `DefaultThemeRenderContext`.
 -   Renamed `navigation` to `sidebar` on `DefaultThemeRenderContext` and `navigation.begin`/`navigation.end` hooks to `sidebar.begin`/`sidebar.end`.
 
 ### Features
 
+-   Added `--useTsLinkResolution` option (on by default) which tells TypeDoc to use TypeScript's `@link` resolution.
+-   Reworked default theme navigation to add support for a page table of contents, #1478, #2189.
 -   Added support for `@interface` on type aliases to tell TypeDoc to convert the fully resolved type as an interface, #1519
+-   Added support for `@namespace` on variable declarations to tell TypeDoc to convert the variable as a namespace, #2055.
 -   Added support for `@prop`/`@property` to specify documentation for a child property of a symbol, intended for use with `@interface`.
+-   TypeDoc will now produce more informative error messages for options which cannot be set from the cli, #2022.
+-   TypeDoc will now attempt to guess what option you may have meant if given an invalid option name.
 -   Plugins may now return a `Promise<void>` from their `load` function, #185.
 -   TypeDoc now supports plugins written with ESM, #1635.
 -   Added `Renderer.preRenderAsyncJobs` and `Renderer.postRenderAsyncJobs`, which may be used by plugins to perform async processing for rendering, #185.
     Note: Conversion is still intentionally a synchronous process to ensure stability of converted projects between runs.
--   TypeDoc will now produce more informative error messages for options which cannot be set from the cli, #2022.
--   TypeDoc will now attempt to guess what option you may have meant if given an invalid option name.
 -   TypeDoc options may now be set under the `typedocOptions` key in `package.json`, #2112.
--   Moved sidebar to left of content for consistency with most other websites, #2189.
 -   Added `--cacheBust` option to tell TypeDoc to include include the generation time in files, #2124.
--   Added support for `@namespace` on variable declarations to tell TypeDoc to convert the variable as a namespace, #2055.
 -   Added `--excludeReferences` option to tell TypeDoc to omit re-exports of a symbol already included from the documentation.
 -   Introduced new render hooks `pageSidebar.begin` and `pageSidebar.end`.
 

src/lib/output/components.ts

@@ -1,9 +1,9 @@
 import * as Path from "path";
 
 import { Component, AbstractComponent } from "../utils/component";
-import {
+import type {
     ProjectReflection,
-    DeclarationReflection,
+    Reflection,
 } from "../models/reflections/index";
 import type { Renderer } from "./renderer";
 import { RendererEvent, PageEvent } from "./events";
@@ -24,7 +24,7 @@ export abstract class ContextAwareRendererComponent extends RendererComponent {
     /**
      * The reflection that is currently processed.
      */
-    protected reflection?: DeclarationReflection;
+    protected page?: PageEvent<Reflection>;
 
     /**
      * The url of the document that is being currently generated.
@@ -84,11 +84,8 @@ export abstract class ContextAwareRendererComponent extends RendererComponent {
      *
      * @param page  An event object describing the current render operation.
      */
-    protected onBeginPage(page: PageEvent) {
+    protected onBeginPage(page: PageEvent<Reflection>) {
         this.location = page.url;
-        this.reflection =
-            page.model instanceof DeclarationReflection
-                ? page.model
-                : undefined;
+        this.page = page;
     }
 }

src/lib/output/events.ts

@@ -3,7 +3,7 @@ import * as Path from "path";
 import { Event } from "../utils/events";
 import type { ProjectReflection } from "../models/reflections/project";
 import type { RenderTemplate, UrlMapping } from "./models/UrlMapping";
-import type { DeclarationReflection } from "../models";
+import type { DeclarationReflection, ReflectionKind } from "../models";
 
 /**
  * An event emitted by the {@link Renderer} class at the very beginning and
@@ -61,14 +61,12 @@ export class RendererEvent extends Event {
      */
     public createPageEvent<Model>(
         mapping: UrlMapping<Model>
-    ): PageEvent<Model> {
-        const event = new PageEvent<Model>(PageEvent.BEGIN);
+    ): [RenderTemplate<PageEvent<Model>>, PageEvent<Model>] {
+        const event = new PageEvent<Model>(PageEvent.BEGIN, mapping.model);
         event.project = this.project;
         event.url = mapping.url;
-        event.model = mapping.model;
-        event.template = mapping.template;
         event.filename = Path.join(this.outputDirectory, mapping.url);
-        return event;
+        return [mapping.template, event];
     }
 }
 
@@ -79,7 +77,7 @@ export class RendererEvent extends Event {
  * @see {@link Renderer.EVENT_BEGIN_PAGE}
  * @see {@link Renderer.EVENT_END_PAGE}
  */
-export class PageEvent<Model = unknown> extends Event {
+export class PageEvent<out Model = unknown> extends Event {
     /**
      * The project the renderer is currently processing.
      */
@@ -98,12 +96,7 @@ export class PageEvent<Model = unknown> extends Event {
     /**
      * The model that should be rendered on this page.
      */
-    model!: Model;
-
-    /**
-     * The template that should be used to render this page.
-     */
-    template!: RenderTemplate<this>;
+    readonly model: Model;
 
     /**
      * The final html content of this page.
@@ -112,6 +105,18 @@ export class PageEvent<Model = unknown> extends Event {
      */
     contents?: string;
 
+    /**
+     * Links to content within this page that should be rendered in the page navigation.
+     * This is built when rendering the document content.
+     */
+    pageHeadings: Array<{
+        link: string;
+        text: string;
+        level?: number;
+        kind?: ReflectionKind;
+        classes?: string;
+    }> = [];
+
     /**
      * Triggered before a document will be rendered.
      * @event
@@ -123,12 +128,17 @@ export class PageEvent<Model = unknown> extends Event {
      * @event
      */
     static readonly END = "endPage";
+
+    constructor(name: string, model: Model) {
+        super(name);
+        this.model = model;
+    }
 }
 
 /**
  * An event emitted when markdown is being parsed. Allows other plugins to manipulate the result.
  *
- * @see {@link PARSE}
+ * @see {@link MarkdownEvent.PARSE}
  */
 export class MarkdownEvent extends Event {
     /**
@@ -141,14 +151,25 @@ export class MarkdownEvent extends Event {
      */
     parsedText: string;
 
+    /**
+     * The page that this markdown is being parsed for.
+     */
+    readonly page: PageEvent;
+
     /**
      * Triggered on the renderer when this plugin parses a markdown string.
      * @event
      */
     static readonly PARSE = "parseMarkdown";
 
-    constructor(name: string, originalText: string, parsedText: string) {
+    constructor(
+        name: string,
+        page: PageEvent,
+        originalText: string,
+        parsedText: string
+    ) {
         super(name);
+        this.page = page;
         this.originalText = originalText;
         this.parsedText = parsedText;
     }

src/lib/output/plugins/JavascriptIndexPlugin.ts

@@ -105,9 +105,7 @@ export class JavascriptIndexPlugin extends RendererComponent {
                 kind: reflection.kind,
                 name: reflection.name,
                 url: reflection.url,
-                classes: this.owner.theme
-                    .getRenderContext()
-                    .getReflectionClasses(reflection),
+                classes: this.owner.theme.getReflectionClasses(reflection),
             };
 
             if (parent) {

src/lib/output/renderer.ts

@@ -13,7 +13,7 @@ import type { Application } from "../application";
 import type { Theme } from "./theme";
 import { RendererEvent, PageEvent, IndexEvent } from "./events";
 import type { ProjectReflection } from "../models/reflections/project";
-import type { UrlMapping } from "./models/UrlMapping";
+import type { RenderTemplate, UrlMapping } from "./models/UrlMapping";
 import { writeFileSync } from "../utils/fs";
 import { DefaultTheme } from "./themes/default/DefaultTheme";
 import { RendererComponent } from "./components";
@@ -260,7 +260,7 @@ export class Renderer extends ChildableComponent<
             );
             output.urls.forEach((mapping: UrlMapping) => {
                 clearSeenIconCache();
-                this.renderDocument(output.createPageEvent(mapping));
+                this.renderDocument(...output.createPageEvent(mapping));
                 validateStateIsClean(mapping.url);
             });
 
@@ -282,7 +282,10 @@ export class Renderer extends ChildableComponent<
      * @param page An event describing the current page.
      * @return TRUE if the page has been saved to disc, otherwise FALSE.
      */
-    private renderDocument(page: PageEvent) {
+    private renderDocument(
+        template: RenderTemplate<PageEvent<Reflection>>,
+        page: PageEvent<Reflection>
+    ) {
         const momento = this.hooks.saveMomento();
         this.trigger(PageEvent.BEGIN, page);
         if (page.isDefaultPrevented) {
@@ -291,7 +294,7 @@ export class Renderer extends ChildableComponent<
         }
 
         if (page.model instanceof Reflection) {
-            page.contents = this.theme!.render(page as PageEvent<Reflection>);
+            page.contents = this.theme!.render(page, template);
         } else {
             throw new Error("Should be unreachable");
         }

src/lib/output/theme.ts

@@ -1,6 +1,6 @@
 import type { Renderer } from "./renderer";
 import type { ProjectReflection } from "../models/reflections/project";
-import type { UrlMapping } from "./models/UrlMapping";
+import type { RenderTemplate, UrlMapping } from "./models/UrlMapping";
 import { RendererComponent } from "./components";
 import { Component } from "../utils/component";
 import type { PageEvent } from "./events";
@@ -46,5 +46,8 @@ export abstract class Theme extends RendererComponent {
     /**
      * Renders the provided page to a string, which will be written to disk by the {@link Renderer}
      */
-    abstract render(page: PageEvent<Reflection>): string;
+    abstract render(
+        page: PageEvent<Reflection>,
+        template: RenderTemplate<PageEvent<Reflection>>
+    ): string;
 }

src/lib/output/themes/MarkedPlugin.ts

@@ -3,23 +3,11 @@ import * as Path from "path";
 import * as Marked from "marked";
 
 import { Component, ContextAwareRendererComponent } from "../components";
-import { RendererEvent, MarkdownEvent } from "../events";
+import { RendererEvent, MarkdownEvent, PageEvent } from "../events";
 import { BindOption, readFile, copySync, isFile } from "../../utils";
 import { highlight, isSupportedLanguage } from "../../utils/highlighter";
 import type { Theme } from "shiki";
 
-const customMarkedRenderer = new Marked.Renderer();
-
-customMarkedRenderer.heading = (text, level, _, slugger) => {
-    const slug = slugger.slug(text);
-
-    return `
-<a href="#${slug}" id="${slug}" style="color: inherit; text-decoration: none;">
-  <h${level}>${text}</h${level}>
-</a>
-`;
-};
-
 /**
  * Implements markdown and relativeURL helpers for templates.
  * @internal
@@ -100,7 +88,7 @@ output file :
      * @param text  The markdown string that should be parsed.
      * @returns The resulting html string.
      */
-    public parseMarkdown(text: string) {
+    public parseMarkdown(text: string, page: PageEvent<any>) {
         if (this.includes) {
             text = text.replace(this.includePattern, (_match, path) => {
                 path = Path.join(this.includes!, path.trim());
@@ -134,7 +122,7 @@ output file :
             );
         }
 
-        const event = new MarkdownEvent(MarkdownEvent.PARSE, text, text);
+        const event = new MarkdownEvent(MarkdownEvent.PARSE, page, text, text);
 
         this.owner.trigger(event);
         return event.parsedText;
@@ -195,7 +183,22 @@ output file :
         // Set some default values if they are not specified via the TypeDoc option
         markedOptions.highlight ??= (text, lang) =>
             this.getHighlighted(text, lang);
-        markedOptions.renderer ??= customMarkedRenderer;
+
+        if (!markedOptions.renderer) {
+            markedOptions.renderer = new Marked.Renderer();
+
+            markedOptions.renderer.heading = (text, level, _, slugger) => {
+                const slug = slugger.slug(text);
+                // Prefix the slug with an extra `$` to prevent conflicts with TypeDoc's anchors.
+                this.page!.pageHeadings.push({
+                    link: `#$${slug}`,
+                    text,
+                    level,
+                });
+                return `<a id="$${slug}" class="tsd-anchor"></a><h${level}><a href="#$${slug}" style="color:inherit;text-decoration:none">${text}</a></h${level}>`;
+            };
+        }
+
         markedOptions.mangle ??= false; // See https://github.com/TypeStrong/typedoc/issues/1395
 
         return markedOptions;