typedoc-plugin-markdown - npm Package Compare versions

Comparing version 4.0.0-next.54 to 4.0.0-next.55

dist/app/events/markdown-page-event.d.ts

 import { Event, ProjectReflection, Reflection } from 'typedoc';
-export declare class MarkdownPageEvent<out Model = Reflection> extends Event {
+/**
+ * An event emitted by before and after the markup of a page is rendered.
+ *
+ * @usage
+ *
+ * ```ts
+ * export function load(app: MarkdownAppication) {
+ *   app.renderer.on(MarkdownPageEvent.END, (event: MarkdownPageEvent) => {
+ *    events.contents = event.contents.replace('foo', 'bar');
+ *   });
+ * });
+ * ```
+ *
+ * @category Application
+ */
+export declare class MarkdownPageEvent<
+/** @ignore **/ Model = Reflection> extends Event {
+    /**
+     * The project the renderer is currently processing.
+     */
     project: ProjectReflection;
+    /**
+     * The model that should be rendered on this page.
+     */
+    readonly model: Model;
+    /**
+     * The final markdown content of this page.
+     *
+     * Should be rendered by layout templates and can be modified by plugins.
+     */
+    contents?: string;
+    /**
+     * The url this page will be located at.
+     */
+    url: string;
+    /**
+     * The filename the page will be written to.
+     */
     filename: string;
-    url: string;
-    contents?: string;
-    frontmatter?: any;
+    /**
+     * The frontmatter of this page represented as a key value object. This property can be utilised by other plugins.
+     */
+    frontmatter?: Record<string, any>;
+    /**
+     * This is required for typing purposes but is unused in the Markdown theme.
+     * @hidden
+     */
     pageHeadings: any;
-    readonly model: Model;
+    /**
+     * Triggered before a document will be rendered.
+     * @event
+     */
     static readonly BEGIN = "beginPage";
+    /**
+     * Triggered after a document has been rendered, just before it is written to disc.
+     * @event
+     */
     static readonly END = "endPage";
+    /**
+     * @ignore
+     */
     constructor(name: string, model: Model);
 }

dist/app/events/markdown-page-event.js

@@ -5,3 +5,21 @@ "use strict";
 const typedoc_1 = require("typedoc");
+/**
+ * An event emitted by before and after the markup of a page is rendered.
+ *
+ * @usage
+ *
+ * ```ts
+ * export function load(app: MarkdownAppication) {
+ *   app.renderer.on(MarkdownPageEvent.END, (event: MarkdownPageEvent) => {
+ *    events.contents = event.contents.replace('foo', 'bar');
+ *   });
+ * });
+ * ```
+ *
+ * @category Application
+ */
 class MarkdownPageEvent extends typedoc_1.Event {
+    /**
+     * @ignore
+     */
     constructor(name, model) {
@@ -13,3 +31,11 @@ super(name);
 exports.MarkdownPageEvent = MarkdownPageEvent;
+/**
+ * Triggered before a document will be rendered.
+ * @event
+ */
 MarkdownPageEvent.BEGIN = 'beginPage';
+/**
+ * Triggered after a document has been rendered, just before it is written to disc.
+ * @event
+ */
 MarkdownPageEvent.END = 'endPage';

dist/app/events/markdown-renderer-event.d.ts

 /**
  * Extends the RendererEvent from TypeDoc to expose navigation property.
+ *
  */
-import { MarkdownPageEvent } from '../../app/events';
+import { MarkdownPageEvent } from '../events/markdown-page-event';
 import { NavigationItem, RenderTemplate, UrlMapping } from '../../theme/theme-types';
 import { Event, ProjectReflection, Reflection } from 'typedoc';
+/**
+ * An event emitted at the beginning and end of the rendering process.
+ *
+ * @usage
+ *
+ * ```ts
+ * app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => {
+ *   console.log(`Render Starting for ${event.project.name}!`);
+ * });
+ * ```
+ *
+ * @category Application
+ */
 export declare class MarkdownRendererEvent extends Event {
+    /**
+     * The project the renderer is currently processing.
+     */
     readonly project: ProjectReflection;
+    /**
+     * The path of the directory the documentation should be written to.
+     */
     readonly outputDirectory: string;
+    /**
+     * A list of all pages that should be generated.
+     */
     urls?: UrlMapping<Reflection>[];
-    navigation: NavigationItem[];
+    /**
+     * The navigation structure of the project that can be utilised by plugins.
+     */
+    navigation?: NavigationItem[];
+    /**
+     * Triggered before the renderer starts rendering a project.
+     * @event
+     */
     static readonly BEGIN = "beginRender";
+    /**
+     * Triggered after the renderer has written all documents.
+     * @event
+     */
     static readonly END = "endRender";
     /**
-     * @hidden
+     * @ignore
      */
     constructor(name: string, outputDirectory: string, project: ProjectReflection);
     /**
-     * @hidden
+     * @ignore
      */
     createPageEvent<Model>(mapping: UrlMapping<Model>): [RenderTemplate<MarkdownPageEvent<Model>>, MarkdownPageEvent<Model>];
 }

dist/app/events/markdown-renderer-event.js

 "use strict";
 /**
  * Extends the RendererEvent from TypeDoc to expose navigation property.
+ *
  */
@@ -30,8 +31,21 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
 exports.MarkdownRendererEvent = void 0;
-const events_1 = require("../../app/events");
+const markdown_page_event_1 = require("../events/markdown-page-event");
 const path = __importStar(require("path"));
 const typedoc_1 = require("typedoc");
+/**
+ * An event emitted at the beginning and end of the rendering process.
+ *
+ * @usage
+ *
+ * ```ts
+ * app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => {
+ *   console.log(`Render Starting for ${event.project.name}!`);
+ * });
+ * ```
+ *
+ * @category Application
+ */
 class MarkdownRendererEvent extends typedoc_1.Event {
     /**
-     * @hidden
+     * @ignore
      */
@@ -44,6 +58,6 @@ constructor(name, outputDirectory, project) {
     /**
-     * @hidden
+     * @ignore
      */
     createPageEvent(mapping) {
-        const event = new events_1.MarkdownPageEvent(events_1.MarkdownPageEvent.BEGIN, mapping.model);
+        const event = new markdown_page_event_1.MarkdownPageEvent(markdown_page_event_1.MarkdownPageEvent.BEGIN, mapping.model);
         event.project = this.project;
@@ -56,3 +70,11 @@ event.url = mapping.url;
 exports.MarkdownRendererEvent = MarkdownRendererEvent;
+/**
+ * Triggered before the renderer starts rendering a project.
+ * @event
+ */
 MarkdownRendererEvent.BEGIN = 'beginRender';
+/**
+ * Triggered after the renderer has written all documents.
+ * @event
+ */
 MarkdownRendererEvent.END = 'endRender';

dist/app/renderer/overrides.js

@@ -27,3 +27,4 @@ "use strict";
 exports.render = exports.generateDocs = void 0;
-const events_1 = require("../../app/events");
+const markdown_page_event_1 = require("../events/markdown-page-event");
+const markdown_renderer_event_1 = require("../events/markdown-renderer-event");
 const fs = __importStar(require("fs"));
@@ -83,3 +84,3 @@ const path = __importStar(require("path"));
     this.prepareTheme();
-    const output = new events_1.MarkdownRendererEvent(events_1.MarkdownRendererEvent.BEGIN, outputDirectory, project);
+    const output = new markdown_renderer_event_1.MarkdownRendererEvent(markdown_renderer_event_1.MarkdownRendererEvent.BEGIN, outputDirectory, project);
     output.urls = this.theme.getUrls(project);
@@ -90,32 +91,34 @@ output.navigation = this.theme.getNavigation(project);
     this.preRenderAsyncJobs = [];
-    this.application.logger.verbose(`There are ${output.urls?.length} pages to write.`);
-    output.urls
-        ?.filter((urlMapping) => urlMapping.model instanceof typedoc_1.ProjectReflection ||
-        urlMapping.model instanceof typedoc_1.DeclarationReflection)
-        .forEach(async (urlMapping) => {
-        const [template, page] = output.createPageEvent(urlMapping);
-        this.trigger(events_1.MarkdownPageEvent.BEGIN, page);
-        if (page.isDefaultPrevented) {
-            return false;
-        }
-        if (page.model instanceof typedoc_1.Reflection) {
-            page.contents = this.theme.render(page, template);
-        }
-        else {
-            throw new Error('Should be unreachable');
-        }
-        this.trigger(events_1.MarkdownPageEvent.END, page);
-        if (page.isDefaultPrevented) {
-            return false;
-        }
-        try {
-            writeFileSync(page.filename, page.contents);
-        }
-        catch (error) {
-            this.application.logger.error(`Could not write ${page.filename}`);
-        }
-    });
-    this.trigger(events_1.MarkdownRendererEvent.END, output);
-    await Promise.all(this.postRenderAsyncJobs.map((job) => job(output)));
-    this.postRenderAsyncJobs = [];
+    if (!output.isDefaultPrevented) {
+        this.application.logger.verbose(`There are ${output.urls?.length} pages to write.`);
+        output.urls
+            ?.filter((urlMapping) => urlMapping.model instanceof typedoc_1.ProjectReflection ||
+            urlMapping.model instanceof typedoc_1.DeclarationReflection)
+            .forEach(async (urlMapping) => {
+            const [template, page] = output.createPageEvent(urlMapping);
+            this.trigger(markdown_page_event_1.MarkdownPageEvent.BEGIN, page);
+            if (page.isDefaultPrevented) {
+                return false;
+            }
+            if (page.model instanceof typedoc_1.Reflection) {
+                page.contents = this.theme.render(page, template);
+            }
+            else {
+                throw new Error('Should be unreachable');
+            }
+            this.trigger(markdown_page_event_1.MarkdownPageEvent.END, page);
+            if (page.isDefaultPrevented) {
+                return false;
+            }
+            try {
+                writeFileSync(page.filename, page.contents);
+            }
+            catch (error) {
+                this.application.logger.error(`Could not write ${page.filename}`);
+            }
+        });
+        await Promise.all(this.postRenderAsyncJobs.map((job) => job(output)));
+        this.postRenderAsyncJobs = [];
+        this.trigger(markdown_renderer_event_1.MarkdownRendererEvent.END, output);
+    }
     this.theme = void 0;
@@ -122,0 +125,0 @@ }

dist/index.d.ts

@@ -8,10 +8,6 @@ import { Application } from 'typedoc';
  * This method is not intended to be consumed in any other context that via the `plugin` option.
+ *
+ * @ignore
  */
 export declare function load(app: Application): void;
-/**
- * Symbols required for the public api
- */
-export { MarkdownPageEvent, MarkdownRendererEvent } from './app/events';
-export { OutputFileStrategy, PluginOptions } from './app/options';
-export { MarkdownApplication, MarkdownRendererHooks, } from './app/renderer';
-export { MarkdownTheme, MarkdownThemeRenderContext, NavigationItem, } from './theme';
+export * from './public-api';

dist/index.js

@@ -25,7 +25,11 @@ "use strict";
 };
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MarkdownThemeRenderContext = exports.MarkdownTheme = exports.OutputFileStrategy = exports.MarkdownRendererEvent = exports.MarkdownPageEvent = exports.load = void 0;
-const declarations = __importStar(require("./app/options/declarations"));
-const renderer_1 = require("./app/renderer");
-const theme_1 = require("./theme");
+exports.load = void 0;
+const overrides_1 = require("./app/renderer/overrides");
+const packages_1 = require("./app/renderer/packages");
+const declarations = __importStar(require("./options/declarations"));
+const base_1 = require("./theme/base");
 const typedoc_1 = require("typedoc");
@@ -38,2 +42,4 @@ /**
  * This method is not intended to be consumed in any other context that via the `plugin` option.
+ *
+ * @ignore
  */
@@ -70,3 +76,3 @@ function load(app) {
         value: new Map([
-            ['default', theme_1.MarkdownTheme],
+            ['default', base_1.MarkdownTheme],
         ]),
@@ -77,3 +83,3 @@ });
      */
-    Object.defineProperty(app, 'generateDocs', { value: renderer_1.generateDocs });
+    Object.defineProperty(app, 'generateDocs', { value: overrides_1.generateDocs });
     /**
@@ -83,3 +89,3 @@ * Replace TypeDoc's {@link app.renderer.render} method with our own {@link render} method.
     Object.defineProperty(app.renderer, 'render', {
-        value: renderer_1.render,
+        value: overrides_1.render,
     });
@@ -107,3 +113,3 @@ /**
         if (app.options.packageDir) {
-            (0, renderer_1.resolvePackages)(app, context, app.options.packageDir);
+            (0, packages_1.resolvePackages)(app, context, app.options.packageDir);
         }
@@ -113,12 +119,2 @@ });
 exports.load = load;
-/**
- * Symbols required for the public api
- */
-var events_1 = require("./app/events");
-Object.defineProperty(exports, "MarkdownPageEvent", { enumerable: true, get: function () { return events_1.MarkdownPageEvent; } });
-Object.defineProperty(exports, "MarkdownRendererEvent", { enumerable: true, get: function () { return events_1.MarkdownRendererEvent; } });
-var options_1 = require("./app/options");
-Object.defineProperty(exports, "OutputFileStrategy", { enumerable: true, get: function () { return options_1.OutputFileStrategy; } });
-var theme_2 = require("./theme");
-Object.defineProperty(exports, "MarkdownTheme", { enumerable: true, get: function () { return theme_2.MarkdownTheme; } });
-Object.defineProperty(exports, "MarkdownThemeRenderContext", { enumerable: true, get: function () { return theme_2.MarkdownThemeRenderContext; } });
+__exportStar(require("./public-api"), exports);

dist/theme/lib/utils/index.d.ts

@@ -10,2 +10,3 @@ export { camelToTitleCase } from './camel-to-title-case';
 export { removeFirstScopedDirectory } from './remove-first-scoped-directory';
+export { slugifyUrl } from './slugify-url';
 export { stripComments } from './strip-comments';

dist/theme/lib/utils/index.js

 "use strict";
 // PLEASE NOTE: THE CONTENTS OF THE FILE BELOW THIS POINT IS AUTO GENERATED!
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripComments = exports.removeFirstScopedDirectory = exports.pipe = exports.getFirstParagrph = exports.getFileNameWithExtension = exports.formatTableTypeCol = exports.formatTableNameCol = exports.formatTableDescriptionCol = exports.escapeChars = exports.camelToTitleCase = void 0;
+exports.stripComments = exports.slugifyUrl = exports.removeFirstScopedDirectory = exports.pipe = exports.getFirstParagrph = exports.getFileNameWithExtension = exports.formatTableTypeCol = exports.formatTableNameCol = exports.formatTableDescriptionCol = exports.escapeChars = exports.camelToTitleCase = void 0;
 var camel_to_title_case_1 = require("./camel-to-title-case");
@@ -23,3 +23,5 @@ Object.defineProperty(exports, "camelToTitleCase", { enumerable: true, get: function () { return camel_to_title_case_1.camelToTitleCase; } });
 Object.defineProperty(exports, "removeFirstScopedDirectory", { enumerable: true, get: function () { return remove_first_scoped_directory_1.removeFirstScopedDirectory; } });
+var slugify_url_1 = require("./slugify-url");
+Object.defineProperty(exports, "slugifyUrl", { enumerable: true, get: function () { return slugify_url_1.slugifyUrl; } });
 var strip_comments_1 = require("./strip-comments");
 Object.defineProperty(exports, "stripComments", { enumerable: true, get: function () { return strip_comments_1.stripComments; } });

dist/theme/theme-types.d.ts

@@ -1,3 +0,19 @@
-import { MarkdownPageEvent } from '../app/events';
+import { MarkdownPageEvent } from '../app/events/markdown-page-event';
+import { OutputFileStrategy } from '../options/option-maps';
 import { ReflectionKind } from 'typedoc';
+/**
+ * The model used to define the URL mapping structure.
+ *
+ * @category Custom Theme
+ */
+export interface UrlMapping</** @ignore */ Model> {
+    url: string;
+    model: Model;
+    template: (data: MarkdownPageEvent<Model>) => string;
+}
+/**
+ * The model used to define the navigation structure.
+ *
+ * @category Custom Theme
+ */
 export interface NavigationItem {
@@ -7,5 +23,4 @@ title: string;
     children?: NavigationItem[];
-    isReadme?: boolean;
-    isGroup?: boolean;
 }
+export type RenderTemplate<T> = (data: T) => string;
 export interface TemplateMapping {
@@ -16,7 +31,9 @@ directory: string | null;
 }
-export interface UrlMapping<Model> {
-    url: string;
-    model: Model;
-    template: RenderTemplate<MarkdownPageEvent<Model>>;
+export interface UrlOption {
+    parentUrl?: string;
+    directory?: string | null;
+    forceDirectory?: boolean;
+    outputFileStrategy?: OutputFileStrategy;
+    entryModule?: string;
+    entryFileName?: string;
 }
-export type RenderTemplate<T> = (data: T) => string;

package.json

 {
   "name": "typedoc-plugin-markdown",
-  "version": "4.0.0-next.54",
+  "version": "4.0.0-next.55",
   "description": "A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.",
@@ -12,3 +12,3 @@ "main": "dist/index.js",
     "prepublishOnly": "npm run lint && npm run build",
-    "prebuild": "rm -rf dist && prebuild-options && ts-node scripts/prebuild",
+    "prebuild": "rm -rf dist && prebuild-options && ts-node ./.scripts/prebuild",
     "build": "tsc && tsc-alias",
@@ -22,3 +22,3 @@ "build-and-run": "npm run build && npm run pretest",
     "predocs": "npm run build",
-    "docs": "typedoc --options ./typedoc.devdocs.json && typedoc --options ./typedoc.base.json --out ./html"
+    "docs": "typedoc --options ./.docs/typedoc.md.cjs && typedoc --options ./.docs/typedoc.html.cjs"
   },
@@ -25,0 +25,0 @@ "author": "Thomas Grey",

README.md

@@ -15,2 +15,2 @@ # typedoc-plugin-markdown
 
-Please visit [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org) for comprehensive documentation, including options and usage guides.
+Please visit [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org/docs) for comprehensive documentation, including options and usage guides.

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

299106

increased by2.17%

Lines of code

7742

increased by5.25%

Worsened metrics

Number of package files

235

decreased by-0.84%

No dependency changes