typedoc 0.23.16 → 0.23.17

package/dist/lib/converter/plugins/SourcePlugin.d.ts

@@ -6,6 +6,7 @@ export declare class SourcePlugin extends ConverterComponent {
     readonly disableSources: boolean;
     readonly gitRevision: string;
     readonly gitRemote: string;
+    readonly sourceLinkTemplate: string;
     readonly basePath: string;
     /**
      * All file names to find the base path from.

package/dist/lib/converter/plugins/SourcePlugin.js

@@ -100,10 +100,7 @@ let SourcePlugin = class SourcePlugin extends components_1.ConverterComponent {
             for (const source of refl.sources || []) {
                 if (repository_1.gitIsInstalled) {
                     const repo = this.getRepository(source.fullFileName);
-                    source.url = repo?.getURL(source.fullFileName);
-                    if (source.url) {
-                        source.url += `#${repo.getLineNumberAnchor(source.line)}`;
-                    }
+                    source.url = repo?.getURL(source.fullFileName, source.line);
                 }
                 source.fileName = (0, fs_1.normalizePath)((0, path_1.relative)(basePath, source.fullFileName));
             }
@@ -131,7 +128,7 @@ let SourcePlugin = class SourcePlugin extends components_1.ConverterComponent {
             }
         }
         // Try to create a new repository
-        const repository = repository_1.Repository.tryCreateRepository(dirName, this.gitRevision, this.gitRemote, this.application.logger);
+        const repository = repository_1.Repository.tryCreateRepository(dirName, this.sourceLinkTemplate, this.gitRevision, this.gitRemote, this.application.logger);
         if (repository) {
             this.repositories[repository.path.toLowerCase()] = repository;
             return repository;
@@ -149,6 +146,9 @@ __decorate([
 __decorate([
     (0, utils_1.BindOption)("gitRemote")
 ], SourcePlugin.prototype, "gitRemote", void 0);
+__decorate([
+    (0, utils_1.BindOption)("sourceLinkTemplate")
+], SourcePlugin.prototype, "sourceLinkTemplate", void 0);
 __decorate([
     (0, utils_1.BindOption)("basePath")
 ], SourcePlugin.prototype, "basePath", void 0);

package/dist/lib/converter/utils/repository.d.ts

@@ -12,28 +12,21 @@ export declare class Repository {
      * All files tracked by the repository.
      */
     files: Set<string>;
-    /**
-     * The base url for link creation.
-     */
-    baseUrl: string;
-    /**
-     * The anchor prefix used to select lines, usually `L`
-     */
-    anchorPrefix: string;
+    urlTemplate: string;
+    gitRevision: string;
     /**
      * Create a new Repository instance.
      *
      * @param path  The root path of the repository.
      */
-    constructor(path: string, baseUrl: string);
+    constructor(path: string, gitRevision: string, urlTemplate: string);
     /**
      * Get the URL of the given file on GitHub or Bitbucket.
      *
      * @param fileName  The file whose URL should be determined.
      * @returns A URL pointing to the web preview of the given file or undefined.
      */
-    getURL(fileName: string): string | undefined;
-    getLineNumberAnchor(lineNumber: number): string;
+    getURL(fileName: string, line: number): string | undefined;
     /**
      * Try to create a new repository instance.
      *
@@ -43,6 +36,6 @@ export declare class Repository {
      * @param path  The potential repository root.
      * @returns A new instance of {@link Repository} or undefined.
      */
-    static tryCreateRepository(path: string, gitRevision: string, gitRemote: string, logger: Logger): Repository | undefined;
+    static tryCreateRepository(path: string, sourceLinkTemplate: string, gitRevision: string, gitRemote: string, logger: Logger): Repository | undefined;
 }
-export declare function guessBaseUrl(gitRevision: string, remotes: string[]): string | undefined;
+export declare function guessSourceUrlTemplate(remotes: string[]): string | undefined;

package/dist/lib/converter/utils/repository.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.guessBaseUrl = exports.Repository = exports.gitIsInstalled = void 0;
+exports.guessSourceUrlTemplate = exports.Repository = exports.gitIsInstalled = void 0;
 const child_process_1 = require("child_process");
 const base_path_1 = require("../utils/base-path");
 const TEN_MEGABYTES = 1024 * 10000;
@@ -21,14 +21,14 @@ class Repository {
      *
      * @param path  The root path of the repository.
      */
-    constructor(path, baseUrl) {
+    constructor(path, gitRevision, urlTemplate) {
         /**
          * All files tracked by the repository.
          */
         this.files = new Set();
         this.path = path;
-        this.baseUrl = baseUrl;
-        this.anchorPrefix = guessAnchorPrefix(this.baseUrl);
+        this.gitRevision = gitRevision;
+        this.urlTemplate = urlTemplate;
         const out = git("-C", path, "ls-files");
         if (out.status === 0) {
             out.stdout.split("\n").forEach((file) => {
@@ -44,14 +44,16 @@ class Repository {
      * @param fileName  The file whose URL should be determined.
      * @returns A URL pointing to the web preview of the given file or undefined.
      */
-    getURL(fileName) {
+    getURL(fileName, line) {
         if (!this.files.has(fileName)) {
             return;
         }
-        return `${this.baseUrl}/${fileName.substring(this.path.length + 1)}`;
-    }
-    getLineNumberAnchor(lineNumber) {
-        return `${this.anchorPrefix}${lineNumber}`;
+        const replacements = {
+            gitRevision: this.gitRevision,
+            path: fileName.substring(this.path.length + 1),
+            line,
+        };
+        return this.urlTemplate.replace(/\{(gitRevision|path|line)\}/g, (_, key) => replacements[key]);
     }
     /**
      * Try to create a new repository instance.
@@ -62,29 +64,33 @@ class Repository {
      * @param path  The potential repository root.
      * @returns A new instance of {@link Repository} or undefined.
      */
-    static tryCreateRepository(path, gitRevision, gitRemote, logger) {
+    static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
         const topLevel = git("-C", path, "rev-parse", "--show-toplevel");
         if (topLevel.status !== 0)
             return;
         gitRevision || (gitRevision = git("-C", path, "rev-parse", "--short", "HEAD").stdout.trim());
         if (!gitRevision)
             return; // Will only happen in a repo with no commits.
-        let baseUrl;
-        if (/^https?:\/\//.test(gitRemote)) {
-            baseUrl = `${gitRemote}/${gitRevision}`;
+        let urlTemplate;
+        if (sourceLinkTemplate) {
+            urlTemplate = sourceLinkTemplate;
+        }
+        else if (/^https?:\/\//.test(gitRemote)) {
+            logger.warn("Using a link as the gitRemote is deprecated and will be removed in 0.24.");
+            urlTemplate = `${gitRemote}/{gitRevision}`;
         }
         else {
             const remotesOut = git("-C", path, "remote", "get-url", gitRemote);
             if (remotesOut.status === 0) {
-                baseUrl = guessBaseUrl(gitRevision, remotesOut.stdout.split("\n"));
+                urlTemplate = guessSourceUrlTemplate(remotesOut.stdout.split("\n"));
             }
             else {
                 logger.warn(`The provided git remote "${gitRemote}" was not valid. Source links will be broken.`);
             }
         }
-        if (!baseUrl)
+        if (!urlTemplate)
             return;
-        return new Repository(base_path_1.BasePath.normalize(topLevel.stdout.replace("\n", "")), baseUrl);
+        return new Repository(base_path_1.BasePath.normalize(topLevel.stdout.replace("\n", "")), gitRevision, urlTemplate);
     }
 }
 exports.Repository = Repository;
@@ -100,7 +106,7 @@ const repoExpressions = [
     /(bitbucket.org)[:/]([^/]+)\/(.*)/,
     /(gitlab.com)[:/]([^/]+)\/(.*)/,
 ];
-function guessBaseUrl(gitRevision, remotes) {
+function guessSourceUrlTemplate(remotes) {
     let hostname = "";
     let user = "";
     let project = "";
@@ -121,18 +127,14 @@ function guessBaseUrl(gitRevision, remotes) {
         project = project.slice(0, -4);
     }
     let sourcePath = "blob";
+    let anchorPrefix = "L";
     if (hostname.includes("gitlab")) {
         sourcePath = "-/blob";
     }
     else if (hostname.includes("bitbucket")) {
         sourcePath = "src";
+        anchorPrefix = "lines-";
     }
-    return `https://${hostname}/${user}/${project}/${sourcePath}/${gitRevision}`;
-}
-exports.guessBaseUrl = guessBaseUrl;
-function guessAnchorPrefix(url) {
-    if (url.includes("bitbucket")) {
-        return "lines-";
-    }
-    return "L";
+    return `https://${hostname}/${user}/${project}/${sourcePath}/{gitRevision}/{path}#${anchorPrefix}{line}`;
 }
+exports.guessSourceUrlTemplate = guessSourceUrlTemplate;

package/dist/lib/output/themes/default/DefaultThemeRenderContext.d.ts

@@ -44,6 +44,7 @@ export declare class DefaultThemeRenderContext {
     members: (props: import("../../../models").ContainerReflection) => import("../../../utils/jsx.elements").JsxElement;
     membersGroup: (group: import("../../../models").ReflectionGroup) => import("../../../utils/jsx.elements").JsxElement;
     navigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
+    sidebarLinks: () => import("../../../utils/jsx.elements").JsxElement | null;
     settings: () => import("../../../utils/jsx.elements").JsxElement;
     primaryNavigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
     secondaryNavigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement | undefined;

package/dist/lib/output/themes/default/DefaultThemeRenderContext.js

@@ -77,6 +77,7 @@ class DefaultThemeRenderContext {
         this.members = bind(members_1.members, this);
         this.membersGroup = bind(members_group_1.membersGroup, this);
         this.navigation = bind(navigation_1.navigation, this);
+        this.sidebarLinks = bind(navigation_1.sidebarLinks, this);
         this.settings = bind(navigation_1.settings, this);
         this.primaryNavigation = bind(navigation_1.primaryNavigation, this);
         this.secondaryNavigation = bind(navigation_1.secondaryNavigation, this);

package/dist/lib/output/themes/default/partials/navigation.d.ts

@@ -3,6 +3,7 @@ import { JSX } from "../../../../utils";
 import type { PageEvent } from "../../../events";
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 export declare function navigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element;
+export declare function sidebarLinks(context: DefaultThemeRenderContext): JSX.Element | null;
 export declare function settings(context: DefaultThemeRenderContext): JSX.Element;
 export declare function primaryNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element;
 export declare function secondaryNavigation(context: DefaultThemeRenderContext, props: PageEvent<Reflection>): JSX.Element | undefined;

package/dist/lib/output/themes/default/partials/navigation.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.secondaryNavigation = exports.primaryNavigation = exports.settings = exports.navigation = void 0;
+exports.secondaryNavigation = exports.primaryNavigation = exports.settings = exports.sidebarLinks = exports.navigation = void 0;
 const models_1 = require("../../../../models");
 const utils_1 = require("../../../../utils");
 const lib_1 = require("../../lib");
 function navigation(context, props) {
     return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
+        context.sidebarLinks(),
         context.settings(),
         context.primaryNavigation(props),
         context.secondaryNavigation(props)));
@@ -18,6 +19,13 @@ function buildFilterItem(context, name, displayName, defaultValue) {
             context.icons.checkbox(),
             utils_1.JSX.createElement("span", null, displayName))));
 }
+function sidebarLinks(context) {
+    const links = Object.entries(context.options.getValue("sidebarLinks"));
+    if (!links.length)
+        return null;
+    return (utils_1.JSX.createElement("nav", { id: "tsd-sidebar-links", class: "tsd-navigation" }, links.map(([label, url]) => (utils_1.JSX.createElement("a", { href: url, target: "_blank" }, label)))));
+}
+exports.sidebarLinks = sidebarLinks;
 function settings(context) {
     const defaultFilters = context.options.getValue("visibilityFilters");
     const visibilityOptions = [];

package/dist/lib/output/themes/default/partials/toolbar.js

@@ -6,12 +6,14 @@ const toolbar = (context, props) => (utils_1.JSX.createElement("header", { class
     utils_1.JSX.createElement("div", { class: "tsd-toolbar-contents container" },
         utils_1.JSX.createElement("div", { class: "table-cell", id: "tsd-search", "data-base": context.relativeURL("./") },
             utils_1.JSX.createElement("div", { class: "field" },
-                utils_1.JSX.createElement("label", { for: "tsd-search-field", class: "tsd-widget search no-caption" }, context.icons.search()),
+                utils_1.JSX.createElement("label", { for: "tsd-search-field", class: "tsd-widget tsd-toolbar-icon search no-caption" }, context.icons.search()),
                 utils_1.JSX.createElement("input", { type: "text", id: "tsd-search-field", "aria-label": "Search" })),
+            utils_1.JSX.createElement("div", { class: "field" },
+                utils_1.JSX.createElement("div", { id: "tsd-toolbar-links" }, Object.entries(context.options.getValue("navigationLinks")).map(([label, url]) => (utils_1.JSX.createElement("a", { href: url }, label))))),
             utils_1.JSX.createElement("ul", { class: "results" },
                 utils_1.JSX.createElement("li", { class: "state loading" }, "Preparing search index..."),
                 utils_1.JSX.createElement("li", { class: "state failure" }, "The search index is not available")),
-            utils_1.JSX.createElement("a", { href: context.relativeURL("index.html"), class: "title" }, props.project.name)),
+            utils_1.JSX.createElement("a", { href: context.options.getValue("titleLink") ?? context.relativeURL("index.html"), class: "title" }, props.project.name)),
         utils_1.JSX.createElement("div", { class: "table-cell", id: "tsd-widgets" },
-            utils_1.JSX.createElement("a", { href: "#", class: "tsd-widget menu no-caption", "data-toggle": "menu", "aria-label": "Menu" }, context.icons.menu())))));
+            utils_1.JSX.createElement("a", { href: "#", class: "tsd-widget tsd-toolbar-icon menu no-caption", "data-toggle": "menu", "aria-label": "Menu" }, context.icons.menu())))));
 exports.toolbar = toolbar;

package/dist/lib/utils/options/declaration.d.ts

@@ -74,6 +74,7 @@ export interface TypeDocOptionMap {
     excludeTags: `@${string}`[];
     readme: string;
     cname: string;
+    sourceLinkTemplate: string;
     gitRevision: string;
     gitRemote: string;
     htmlLang: string;
@@ -82,6 +83,9 @@ export interface TypeDocOptionMap {
     hideGenerator: boolean;
     searchInComments: boolean;
     cleanOutputDir: boolean;
+    titleLink: string;
+    navigationLinks: ManuallyValidatedOption<Record<string, string>>;
+    sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
     commentStyle: typeof CommentStyle;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];

package/dist/lib/utils/options/sources/typedoc.js

@@ -235,6 +235,10 @@ function addTypeDocOptions(options) {
         name: "cname",
         help: "Set the CNAME file text, it's useful for custom domains on GitHub Pages.",
     });
+    options.addDeclaration({
+        name: "sourceLinkTemplate",
+        help: "Specify a link template to be used when generating source urls. If not set, will be automatically created using the git remote. Supports {path}, {line}, {gitRevision} placeholders.",
+    });
     options.addDeclaration({
         name: "gitRevision",
         help: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files.",
@@ -276,6 +280,39 @@ function addTypeDocOptions(options) {
         type: declaration_1.ParameterType.Boolean,
         defaultValue: true,
     });
+    options.addDeclaration({
+        name: "titleLink",
+        help: "Set the link the title in the header points to. Defaults to the documentation homepage.",
+        type: declaration_1.ParameterType.String,
+    });
+    options.addDeclaration({
+        name: "navigationLinks",
+        help: "Defines links to be included in the header.",
+        type: declaration_1.ParameterType.Mixed,
+        defaultValue: {},
+        validate(value) {
+            if (!isObject(value)) {
+                throw new Error(`navigationLinks must be an object with string labels as keys and URL values.`);
+            }
+            if (Object.values(value).some((x) => typeof x !== "string")) {
+                throw new Error(`All values of navigationLinks must be string URLs.`);
+            }
+        },
+    });
+    options.addDeclaration({
+        name: "sidebarLinks",
+        help: "Defines links to be included in the sidebar.",
+        type: declaration_1.ParameterType.Mixed,
+        defaultValue: {},
+        validate(value) {
+            if (!isObject(value)) {
+                throw new Error(`sidebarLinks must be an object with string labels as keys and URL values.`);
+            }
+            if (Object.values(value).some((x) => typeof x !== "string")) {
+                throw new Error(`All values of sidebarLinks must be string URLs.`);
+            }
+        },
+    });
     ///////////////////////////
     ///// Comment Options /////
     ///////////////////////////

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.23.16",
+  "version": "0.23.17",
   "homepage": "https://typedoc.org",
   "main": "./dist/index.js",
   "exports": {

package/static/style.css

@@ -825,6 +825,15 @@ input[type="checkbox"]:checked ~ svg .tsd-checkbox-checkmark {
     padding-left: 5.5rem;
 }
 
+#tsd-sidebar-links a {
+    margin-top: 0;
+    margin-bottom: 0.5rem;
+    line-height: 1.25rem;
+}
+#tsd-sidebar-links a:last-of-type {
+    margin-bottom: 0;
+}
+
 a.tsd-index-link {
     margin: 0.25rem 0;
     font-size: 1rem;
@@ -978,7 +987,8 @@ a.tsd-index-link {
     right: -40px;
 }
 #tsd-search .field input,
-#tsd-search .title {
+#tsd-search .title,
+#tsd-toolbar-links a {
     transition: opacity 0.2s;
 }
 #tsd-search .results {
@@ -1022,7 +1032,8 @@ a.tsd-index-link {
     top: 0;
     opacity: 1;
 }
-#tsd-search.has-focus .title {
+#tsd-search.has-focus .title,
+#tsd-search.has-focus #tsd-toolbar-links a {
     z-index: 0;
     opacity: 0;
 }
@@ -1036,6 +1047,22 @@ a.tsd-index-link {
     display: block;
 }
 
+#tsd-toolbar-links {
+    position: absolute;
+    top: 0;
+    right: 2rem;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+}
+#tsd-toolbar-links a {
+    margin-left: 1.5rem;
+}
+#tsd-toolbar-links a:hover {
+    text-decoration: underline;
+}
+
 .tsd-signature {
     margin: 0 0 1rem 0;
     padding: 1rem 0.5rem;
@@ -1134,6 +1161,11 @@ ul.tsd-type-parameter-list h5 {
 .tsd-page-toolbar .table-cell:first-child {
     width: 100%;
 }
+.tsd-page-toolbar .tsd-toolbar-icon {
+    box-sizing: border-box;
+    line-height: 0;
+    padding: 12px 0;
+}
 
 .tsd-page-toolbar--hide {
     transform: translateY(-100%);