typedoc - npm Package Compare versions

Comparing version 0.23.16 to 0.23.17

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

@@ -9,2 +9,3 @@ import { ConverterComponent } from "../components";
     readonly gitRemote: string;
+    readonly sourceLinkTemplate: string;
     readonly basePath: string;
@@ -11,0 +12,0 @@ /**

dist/lib/converter/plugins/SourcePlugin.js

@@ -103,6 +103,3 @@ "use strict";
                     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);
                 }
@@ -135,3 +132,3 @@ source.fileName = (0, fs_1.normalizePath)((0, path_1.relative)(basePath, source.fullFileName));
         // 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) {
@@ -155,2 +152,5 @@ this.repositories[repository.path.toLowerCase()] = repository;
 __decorate([
+    (0, utils_1.BindOption)("sourceLinkTemplate")
+], SourcePlugin.prototype, "sourceLinkTemplate", void 0);
+__decorate([
     (0, utils_1.BindOption)("basePath")
@@ -157,0 +157,0 @@ ], SourcePlugin.prototype, "basePath", void 0);

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

@@ -15,11 +15,5 @@ import type { Logger } from "../../utils";
     files: Set<string>;
+    urlTemplate: string;
+    gitRevision: string;
     /**
-     * The base url for link creation.
-     */
-    baseUrl: string;
-    /**
-     * The anchor prefix used to select lines, usually `L`
-     */
-    anchorPrefix: string;
-    /**
      * Create a new Repository instance.
@@ -29,3 +23,3 @@ *
      */
-    constructor(path: string, baseUrl: string);
+    constructor(path: string, gitRevision: string, urlTemplate: string);
     /**
@@ -37,4 +31,3 @@ * Get the URL of the given file on GitHub or Bitbucket.
      */
-    getURL(fileName: string): string | undefined;
-    getLineNumberAnchor(lineNumber: number): string;
+    getURL(fileName: string, line: number): string | undefined;
     /**
@@ -49,4 +42,4 @@ * Try to create a new repository instance.
      */
-    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;

dist/lib/converter/utils/repository.js

 "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");
@@ -24,3 +24,3 @@ const base_path_1 = require("../utils/base-path");
      */
-    constructor(path, baseUrl) {
+    constructor(path, gitRevision, urlTemplate) {
         /**
@@ -31,4 +31,4 @@ * All files tracked by the repository.
         this.path = path;
-        this.baseUrl = baseUrl;
-        this.anchorPrefix = guessAnchorPrefix(this.baseUrl);
+        this.gitRevision = gitRevision;
+        this.urlTemplate = urlTemplate;
         const out = git("-C", path, "ls-files");
@@ -49,11 +49,13 @@ if (out.status === 0) {
      */
-    getURL(fileName) {
+    getURL(fileName, line) {
         if (!this.files.has(fileName)) {
             return;
         }
-        return `${this.baseUrl}/${fileName.substring(this.path.length + 1)}`;
+        const replacements = {
+            gitRevision: this.gitRevision,
+            path: fileName.substring(this.path.length + 1),
+            line,
+        };
+        return this.urlTemplate.replace(/\{(gitRevision|path|line)\}/g, (_, key) => replacements[key]);
     }
-    getLineNumberAnchor(lineNumber) {
-        return `${this.anchorPrefix}${lineNumber}`;
-    }
     /**
@@ -68,3 +70,3 @@ * Try to create a new repository instance.
      */
-    static tryCreateRepository(path, gitRevision, gitRemote, logger) {
+    static tryCreateRepository(path, sourceLinkTemplate, gitRevision, gitRemote, logger) {
         const topLevel = git("-C", path, "rev-parse", "--show-toplevel");
@@ -76,10 +78,14 @@ if (topLevel.status !== 0)
             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"));
             }
@@ -90,5 +96,5 @@ else {
         }
-        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);
     }
@@ -109,3 +115,3 @@ }
 ];
-function guessBaseUrl(gitRevision, remotes) {
+function guessSourceUrlTemplate(remotes) {
     let hostname = "";
@@ -131,2 +137,3 @@ let user = "";
     let sourcePath = "blob";
+    let anchorPrefix = "L";
     if (hostname.includes("gitlab")) {
@@ -137,11 +144,6 @@ sourcePath = "-/blob";
         sourcePath = "src";
+        anchorPrefix = "lines-";
     }
-    return `https://${hostname}/${user}/${project}/${sourcePath}/${gitRevision}`;
+    return `https://${hostname}/${user}/${project}/${sourcePath}/{gitRevision}/{path}#${anchorPrefix}{line}`;
 }
-exports.guessBaseUrl = guessBaseUrl;
-function guessAnchorPrefix(url) {
-    if (url.includes("bitbucket")) {
-        return "lines-";
-    }
-    return "L";
-}
+exports.guessSourceUrlTemplate = guessSourceUrlTemplate;

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

@@ -47,2 +47,3 @@ import type { RendererHooks } from "../..";
     navigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;
+    sidebarLinks: () => import("../../../utils/jsx.elements").JsxElement | null;
     settings: () => import("../../../utils/jsx.elements").JsxElement;
@@ -49,0 +50,0 @@ primaryNavigation: (props: import("../..").PageEvent<Reflection>) => import("../../../utils/jsx.elements").JsxElement;

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

@@ -80,2 +80,3 @@ "use strict";
         this.navigation = bind(navigation_1.navigation, this);
+        this.sidebarLinks = bind(navigation_1.sidebarLinks, this);
         this.settings = bind(navigation_1.settings, this);
@@ -82,0 +83,0 @@ this.primaryNavigation = bind(navigation_1.primaryNavigation, this);

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

@@ -6,4 +6,5 @@ import { Reflection } from "../../../../models";
 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;

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

 "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");
@@ -9,2 +9,3 @@ const utils_1 = require("../../../../utils");
     return (utils_1.JSX.createElement(utils_1.JSX.Fragment, null,
+        context.sidebarLinks(),
         context.settings(),
@@ -22,2 +23,9 @@ context.primaryNavigation(props),
 }
+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) {
@@ -24,0 +32,0 @@ const defaultFilters = context.options.getValue("visibilityFilters");

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

@@ -9,10 +9,12 @@ "use strict";
             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;

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

@@ -77,2 +77,3 @@ import type { Theme as ShikiTheme } from "shiki";
     cname: string;
+    sourceLinkTemplate: string;
     gitRevision: string;
@@ -86,2 +87,5 @@ gitRemote: string;
     cleanOutputDir: boolean;
+    titleLink: string;
+    navigationLinks: ManuallyValidatedOption<Record<string, string>>;
+    sidebarLinks: ManuallyValidatedOption<Record<string, string>>;
     commentStyle: typeof CommentStyle;
@@ -88,0 +92,0 @@ blockTags: `@${string}`[];

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

@@ -239,2 +239,6 @@ "use strict";
     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",
@@ -280,2 +284,35 @@ help: "Use specified revision instead of the last revision for linking to GitHub/Bitbucket source files.",
     });
+    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.`);
+            }
+        },
+    });
     ///////////////////////////
@@ -282,0 +319,0 @@ ///// Comment Options /////

package.json

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

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1024806

increased by0.37%

Lines of code

24197

increased by0.33%

No dependency changes